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INTRODUCTION  ( INGRES ) 


This  manu.il  is  a  reference  manual  for  the  INGRES  data  base  system.  It  documents  the  use  of 
i\(»ris  in  a  very  terse  manner.  To  learn  how  to  use  INGRES,  refer  to  the  document  called  HA 
Tutorial  on  ingri  s\ 

The  Ingres  reference  manual  is  subdivided  into  four  parts: 

Quel  describes  the  commands  and  features  which  are  used  inside  of  INGRES. 

Unix  describes  the  INGRES  programs  which  are  executable  as  UNIX  commands. 

Files  describes  some  of  the  important  files  used  by  INGRES. 

Error  lists  all  the  user  generatable  error  messages  along  with  some  elaboration  as  to  what 
they  mean  or  what  we  think  they  mean. 

Each  entry  in  this  manual  has  one  or  more  of  the  following  sections: 

NAME  section 

This  section  repeats  the  name  of  the  entry  and  gives  an  indication  of  its  purpose. 
SYNOPSIS  section 

This  section  indicates  the  form  of  the  command  (statement).  The  conventions 
which  are  used  are  as  follows: 

Bold  face  names  are  used  to  indicate  reserved  keywords. 

Lower  case  words  indicate  generic  types  of  information  which  must  be  sup¬ 
plied  by  the  user;  legal  values  for  these  names  are  described 
in  the  DESCRIPTION  section. 

Square  brakets  (  l]  )  indicate  that  the  enclosed  item  is  optional. 

Braces  (  ()  )  indicate  an  optional  item  which  may  be  repeated.  In  some  cases 
they  indicate  simple  (non-repeated)  grouping;  the  usage 
should  be  clear  from  context. 

When  these  conventions  are  insuflfreient  to  fully  specify  the  legal  formal  of  a  com¬ 
mand  a  more  general  form  is  given  and  the  allowable  subsets  are  specified  in  the 
DESCRIPTION  section. 

DESCRIPTION  section 

This  section  gives  a  detailed  description  of  the  entry  with  references  to  the  generic 
names  used  in  the  SYNOPSIS  section. 

EXAMPLE  section 

This  section  gives  one  or  more  examples  of  the  use  of  the  entry.  Most  of  these  ex¬ 
amples  are  based  on  the  following  relations: 

emp(name,sal,mgr,bdate) 

and 

newemp(name,sal,age) 

and 

parts(pnum,  pname,  color,  weight,  qoh) 

SEE  ALSO  section 

This  section  gives  the  names  of  entries  in  the  manual  which  are  closely  related  to 
the  current  entry  or  which  are  referenced  in  the  description  of  the  current  entry. 

BUGS  section 

This  section  indicates  known  bugs  or  deficiencies  in  the  command. 

To  start  using  INGRES  you  must  be  entered  as  an  Ingres  user;  this  is  done  by  the  Ingres  ad- 
minisiraior  who  will  enter  you  in  the  Huser$"  file  (see  users( files)).  To  start  using  ingres  see  the 
section  on  ingres(unix),  quel(quel),  and  monitor(quel). 
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APPEND(QUEL)  -  append  tuples  to  a  relation 

append  (to)  reinume  (target  list)  (where  quail 

COPY  IQIJEL)  copy  data  inU)/from  a  relation  from/into  a  UNIX  file, 
copy  relname  (domname  “  format  {,  domname  *  format  }) 
direction  "filename" 

CREATE(QUEL)  -  create  a  new  relation 

create  relname  domname  /  =»  format  (,  domname2  *  format  )) 

DEFINE(QUEL)  -*  define  subscnema 

define  view  name  (target  list)  (  where  qual  ] 
define  permit  oplist  {  on  |  of  |  to  }  var  (  (attiist)  ] 
to  name  [  at  term  1  [  from  time  to  time  ] 

[  on  day  to  day  1  [  where  qual  1 
define  integrity  on  var  is  qua) 

DELETE(QUEL)  —  delete  tuples  from  a  relation 
delete  tuple_variable  (where  qua!] 

DESTROY(QUEL)  —  destroy  existing  relation(s) 
destroy  relname  (,  relname) 

destroy  [permit  |  integrity]  relname  (integer  {,  integer})  all] 

HELP(QUEL)  -  get  information  about  how  to  use  INGRES  or  about  relations  in  the  database, 
help  [relname]  ["section"]  {,  relname) {,  "section"} 
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index  on  relname  is  indexname  (domain  /  (  , domain,?}) 

INTEGRITY (QUEL)  —  define  integrity  constraints 
define  integrity  on  var  is  qual 

MACROS(QUEL)  —  terminal  monitor  macro  facility 

MODIFY  (QUEL)  —  convert  the  storage  structure  of  a  relation 
modify  relname  to  storage-structure 

[on  keyl  [  :  sortorder  ]  (  (  ,  key2  [  :  sortorder  ]  }  ]  ] 

[  where  [  fillfactor  =  n  ]  [  ,  minpages  =  n  ] 

[  ,  maxpages  =  nn]  ] 

MONITOR  (QUEL)  -  interactive  terminal  monitor 

PERMIT(QUEL)  —  add  permissions  to  a  relation 

define  permit  oplist  (  on  |  of  |  to  }  var  [  (attlist)  1 
to  name  [  at  term  ]  [  from  time  to  time  ] 

[  on  day  to  day  3  I  where  qual  ] 

PRINT(QUEL)  -  print  relation(s) 
print  relname  (,  relname) 

QUEL(QUEL)  -  QUEry  Language  for  Ingres 

RANGE(QUEL)  -  declare  a  variable  to  range  over  a  relation 
range  of  variable  is  relname 

REPLACE(QUEL)  -  replace  values  of  domains  in  a  relation 
replace  tuple^variable  (targetjist)  [where  qual] 

RETRIEVE(QUEL)  -  retrieve  tuples  from  a  relation 

retrieve  [[Into]  relname]  (targetjist)  [where  qual] 
retrieve  unique  (target  jist)  [where  qual] 
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SAVE(QUEL)  —  save  a  relation  until  a  date, 
save  relname  until  month  day  year 

VIEW(QUEL)  -  define  a  virtual  relation 

define  view  name  (target-list)  [  where  qual  ] 
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DESTROYDB(UNIX)  —  destroy  an  existing  database 
destroydb  [  —  s  )  I  —  m  ]  dbname 

EQUEL(UNIX)  -  Embedded  QUEL  interface  to  C 
equel  I  — d  1  (  — f  )  (  — r  ]  file.q  ... 

GEO-QUEL(UNIX)  -  GEO-QUEL  data  display  system 

geoquel  (  —  s  ]  [  — d  ]  [  —a]  (  ~  1 7*  1  (  —  tn7"l  dbname 

HELPR(UNIX)  —  get  information  about  a  database. 

helpr  I  — u name)  I  ±w  )  database  relation  ... 

INGRES(UNIX)  -  INGRES  relational  data  base  management  system 
ingres  ( flags  ]  dbname  [  process_table  1 

PRINTR(UNIX)  -  print  relations 

printr  [  flags)  database  relation  ... 

PURGE(UNIX)  —  destroy  all  expired  and  temporary  relations 

purge  1  — f  1  I  — p  ]  [  — a  1  l  ~s  ]  (  ±w  ]  [  database  ...  ) 

RESTORE(UNIX)  —  recover  from  an  INGRES  or  UNIX  crash, 
restore  l  —a  ]  [  —  s  ]  (  ±w  ]  (  database  ...  ] 

SYSMOD(UNIX)  -  modify  system  relations  to  predetermined  storage  structures. 

sysmod  I  — s  ]  I  — w  ]  dbname  (  relation  ]  (  attribute  ]  [  indexes  1  [  tree  ]  [  protect  ] 
[  integrities  ] 

TIMEFIX(UNIX)  —  patch  INGRES  binary  code  for  correct  timezone. 
timefix  (  —  u  ]  (  — s/V]  [  —  tyyyzzz]  [  —  dX )  filename  ... 

USERSETUP(UNIX)  -  setup  users  file 
.../bin/usersetup  [  pathname  ] 

DAYFILE(FILES)  -  INGRES  login  message 
DBTMPLT(FILES)  -  database  template 
ERROR(FILES)  -  files  with  INGRES  errors 
GRAFILE(FILES)  -  geo-quel  login  message 
LIBQ(FILES)  -  Equel  run-time  support  library 
PROCTAB(FILES)  -  INGRES  runtime  configuration  information 
ST ARTUP( FILES)  -  INGRES  startup  file 
TTYTY  PE  (FILES)  -  GEO-QUEL  terminal  type  database 
USERS(FILES)  -  INGRES  user  codes  and  parameters 
INTRODUCTION  (ERROR)  -  Error  messages  introduction 

EQUEL(ERROR)  -  EQUEL  error  message  summary 
Error  numbers  1000  -  1999. 

PARSER(ERROR)  —  Parser  error  message  summary 
Error  numbers  2000  —  2999. 
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DECOMP(ERROR)  -  Decomposition  error  message  summary 
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NAME 

copy  —  copy  data  inio/from  a  relation  from/into  a  UNIX  file. 

SYNOPSIS 

copy  relname  (domname  =  format  [,  domname  *  formal  |) 
direction  '‘filename" 


DESC  RIPTION 

Copy  moves  data  between  INGRES  relations  and  standard  UNIX  files.  Relname  is  the  name  of  an 
existing  relation.  In  general  domname  identifies  a  domain  in  relname.  Formal  indicates  the  for¬ 
mal  the  UNIX  file  should  have  for  the  corresponding  domain.  Direction  is  either  into  or  from. 
Filename  is  the  full  UNIX  pathname  of  the  file. 

On  a  copy  from  a  file  to  a  relation,  the  relation  cannot  have  a  secondary  index,  it  must  be 
owned  by  you,  and  it  must  be  updatable  (not  a  secondary  index  or  system  relation). 

Copy  cannot  be  used  on  a  relation  which  is  a  view.  For  a  copy  into  a  Unix  file,  you  must  either 
be  the  owner  of  the  relation  or  the  relation  must  have  retrieve  permission  for  all  users,  or  all 
permissions  for  all  users. 

The  formats  allowed  by  copy  are: 

il,i2,i4  —  The  data  is  stored  as  an  integer  of  length  1,  2,  or  4  bytes  in  the  UNIX  file. 

f4,f8  —  The  data  is  stored  as  a  floating  point  number  (either  single  or  double  precision)  in  the 
UNIX  file. 

cl,c2,..Mc255  —  The  data  is  stored  as  a  fixed  length  string  of  characters. 
cO  —  Variable  length  character  string. 
d0,dl,...,d255  —  Dummy  domain. 

Corresponding  domains  in  the  relation  and  the  UNIX  file  do  not  have  to  be  the  same  type  or 
length.  Copy  will  convert  as  necessary.  When  converting  anything  except  character  to  charac¬ 
ter,  copy  checks  for  overflow.  When  converting  from  character  to  character,  copy  will  blank  pad 
or  truncate  on  the  right  as  necessary. 

The  domains  should  be  ordered  according  to  the  way  they  should  appear  in  the  UNIX  file. 
Domains  are  matched  according  to  name,  thus  the  order  of  the  domains  in  the  relation  and  in 
the  UNIX  file  does  not  have  to  be  the  same. 

Copy  also  provides  for  variable  length  strings  and  dummy  domains.  The  action  taken  depends 
on  whether  it  is  a  copy  into  or  a  copy  from.  Delimitors  for  variable  length  strings  and  for  dum¬ 
my  domains  can  be  selected  from  the  list  of: 

nl  —  new  line  character 
tab  -  tab  character 
sp  —  space 

nul  or  null  —  null  character 

comma  —  comma 

colon  —  colon 

dash  —  dash 

Iparen  -  left  parenthesis 

rparen  —  right  parenthesis 

x  —  any  single  character  V 

The  special  meaning  of  any  delimitor  can  be  turned  off  by  preceeding  the  delimiior  with  a  \\ 
The  delimitor  can  optionally  be  in  quotes  ("delim”).  This  is  usefully  if  you  wish  to  use  a  single 
character  delimitor  which  has  special  meaning  to  the  quel  parser. 

When  the  direction  is  from,  copy  appends  data  into  the  relation  from  the  UNIX  file.  Domains  in 
the  INGRES  relation  which  are  not  assigned  values  from  the  UNIX  file  are  assigned  the  default 
value  of  zero  for  numeric  domains,  and  blank  for  character  domains.  When  copying  in  this 
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append  —  append  tuples  to  a  relation 
S\  NOPSIS 

append  [to]  relname  Uargeijist)  [where  qual] 

DESCRIPTION 

ApfH'tuJ  adds  tuples  which  satisfy  the  qualification  to  relname.  Relname  must  be  the  name  of  an 
existing  relation.  The  target  list  specifies  the  values  of  the  attributes  to  be  appended  to  relname . 
The  domains  may  be  listed  in  any  order.  Attributes  of  the  result  relation  which  do  not  appear 
in  the  target Jtst  as  result  attnames  (either  explicitly  or  by  default)  are  assigned  default  values 
of  0,  for  numeric  attributes,  or  blank,  for  character  attributes. 

Values  or  expressions  of  any  numeric  type  may  be  used  to  set  the  value  of  a  numeric  type 
domain.  Conversion  to  (he  result  domain  type  takes  place.  Numeric  values  cannot  be  directly 
assigned  to  character  domains.  Conversion  from  numeric  to  character  can  be  done  using  the 
ascii  operator  (see  quel(quel)).  Character  values  cannot  be  directly  assigned  to  numeric 
domains.  Use  the  inti,  int2,  etc.  functions  to  convert  character  values  to  numeric  (see 
quel(quel) ). 

The  keyword  all  can  be  used  when  it  is  desired  to  append  all  domains  of  a  relation. 

An  append  may  only  be  issued  by  the  owner  of  the  relation  or  a  user  with  append  permission  on 
the  given  relation. 

EXAMPLE 

/*  Make  new'  employee  Jones  work  for  Smith  */ 
range  of  n  is  newemp 

append  to  emp(n.name/n.sal,  mgr  =  ’’Smith”,  bdate  =  1975-n.age) 
where  n.name  =  "Jones” 

/*  Append  the  newempl  relation  to  newemp  */ 
range  of  nl  is  newempl 
append  to  newemp(nl.all) 


SEE  ALSO 

copy(quel),  permit(quel),  quel(quel),  retrieve(quel) 


DIAGNOSTICS 

Use  of  a  numeric  type  expression  to  set  a  character  type  domain  or  vice  versa  will  produce  diag¬ 
nostics. 


Bl  <.S 

Duplicate  tuples  appended  to  a  relation  stored  as  a  "paged  heap”  (unkeyed,  unstructured)  are 
not  removed. 
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direction  ihc  following  special  meanings  apply: 

c0i/t7//#/  —  The  data  in  the  im\  file  is  a  variable  length  character  string  terminated  by  me  del* 
imitor  dctiiii.  It  lid  mi  is  missing  then  the  first  comma,  tab.  or  newline  encountered 
will  terminate  the  siring  The  delimuor  is  not  copied 

For  example. 

pnum-cO  —  string  ending  in  comma,  tab.  or  nl. 

pnum  —  cOnl  —  siring  ending  in  nl. 

pnum  =  cOsp  —  string  ending  in  space. 

pnum  =  cO"Z"  -  siring  ending  in  the  character  "Z". 

pnum  —  cCW  -  string  ending  in  the  character  H%". 

A  delimitor  can  be  escaped  by  preceeding  it  with  a  %V.  For  example,  using  name  = 
cO,  the  string  "Blow\,  Joe."  will  be  accepted  into  the  domain  as  "Blow,  Joe". 

dO ddtm  —  The  data  in  the  UNIX  hie  is  a  variable  length  character  siring  delimited  by  ddtm.  The 
string  is  read  and  discarded.  The  delimitor  rules  are  identical  for  cO  and  dO.  The 
domain  name  is  ignored. 

dl.d2 . d255  -  The  data  in  the  i  \i\  hie  is  a  fixed  length  character  string.  The  string  is  read 

and  discarded.  The  domain  name  is  ignored. 

When  the  direction  is  into,  copy  transfers  data  into  the  UNIX  hie  from  the  relation.  If  the  hie 
already  existed,  it  is  truncated  to  zero  length  before  copying  begins.  When  copying  in  this 
direction,  the  following  special  meanings  apply. 

cO  -  The  domain  value  is  converted  to  a  fixed  length  character  string  and  writted  into  the  i.MX 
hie.  For  character  domains,  the  length  will  be  the  same  as  the  domain  length.  For 
numeric  domains,  the  standard  INGRES  conversions  will  take  place  as  specified  by  the 
i\  f,  and  k  — c'  flags  (see  ingres(unix)). 

c( )ddtm  —  The  domain  will  be  converted  according  to  the  rules  for  cO  above.  The  one  charac¬ 
ter  delimitor  will  be  inserted  immediately  after  the  domain. 

dl,d2,...,d255  —  The  domain  name  is  taken  to  be  the  name  of  the  delimitor,  It  is  written  into 
the  UNIX  hie  1  time  for  dl,  2  times  for  d2,  etc. 

dO  —  This  formal  is  ignored  on  a  copy  into. 

dOddim  —  The  deiim  is  written  into  the  hie.  The  domain  name  is  ignored. 

If  no  domains  appear  in  the  copy  command  (i.e.  copy  relname  0  into/from  '’filename”)  then 
copy  automatically  does  a  "bulk”  copy  of  all  domains,  using  the  order  and  format  of  the  domains 
in  the  relation.  This  is  provided  as  a  convenient  shorthand  notation  for  copying  and  restoring 
entire  relations. 

To  copy  into  a  relation,  you  must  be  the  owner  or  all  users  must  have  all  permissions  set. 
Correspondingly,  to  copy  from  a  relation  you  must  own  the  relation  or  all  users  must  have  at 
least  retrieve  permission  on  the  relation.  Also,  you  may  not  copy  a  v  iew. 

\  \  \MIM  Y 

h  Copy  data  into  the  enip  relation  */ 
copy  emp  ( name  =  c  10. sal  =  f4,bdate  — i2,mgr  =  c  10, xxx  =  dl ) 
from  Vmnt/mc/myfilc" 

h  Copy  employee  names  and  their  salaries  into  a  file  */ 
copy  emp  ( name  =  c0,  command  I,  sal  =  cO,  nl  =d  1 ) 
into  ’Vmnt/you/yourhle" 

/*  Bulk  copy  employee  relation  into  file  */ 
copy  emp  () 

into  ’Vmnt/ours/ourfile" 
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/'  Bulk  copy  employee  relation  from  file  */ 
copy  emp  ( ) 

from  7mni/ihy/thyfi!eM 


\l.SO 

append(quel),  create(quel),  quel(quel),  permit(quel),  view(quel),  ingres(unix) 


Bl  (,S 

Copy  stops  operation  at  the  first  error. 

When  specifying  filename*  the  entire  UMX  directory  pathname  must  be  provided,  since  inc.kks 
operates  out  of  a  different  directory  than  the  user's  working  directory  at  the  time  INGRES  is  in¬ 
voked. 


-  3  - 
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LRLA J  t ( QbhL ) 


\  wit 

(.route  -  create  <i  new  relation 

s\  Norsis 

create  relname  (domname/  =  format  L  domnumcJ  =  format  |) 

OtM  KIIM  IO\ 

C'ttaic  will  enter  a  new  (elution  into  the  data  base.  The  relation  will  be  “owned"  by  'he  user  and 
will  be  set  to  expire  alter  seven  daw  The  name  of  the  relation  is  rchiame  and  the  domains  are 
named  Jonntamcl .  etc  I  he  domains  are  created  with  the  type  specified  bv  lonnuL 

formats  are  described  in  the  gueKquel)  manual  section. 

The  relation  is  created  as  a  paged  heap  with  no  data  initially  in  it. 

A  relation  can  have  no  more  than  49  domains.  A  relation  cannot  have  the  same  name  as  a  sys¬ 
tem  relation. 

FWMPl.F. 

/*  Create  relation  emp  with  domains  name,  sal  and  bdate  */ 
create  emp  (name  =  clO,  salary  =  f’4,  bdate  ~  i2) 

SFF  \LSO 

append(quel),  copy  (quel),  destroy  (quel),  save  (quel) 
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define  "  define  subschema 

SI  \OPSIS 

define  view  name  (target  list)  I  where  qual  ) 
define  permit  oplist  !  on  |  of  |  to  }  var  [  (alt list)  1 
to  name  l  at  term  ]  1  from  time  to  time  i 
(  on  day  to  day  1  (  where  qual  ) 
define  integrity  on  var  is  qual 

MSIRIPTION 

The  define  statement  creates  entries  for  the  subschema  definitions.  See  the  manual  sections 
listed  below  for  complete  descriptions  of  these  commands. 

SKF  At  SO 

iniegrilytquelh  permit(quel),  view(quel) 
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delete  —  delete  tuples  from  a  relation 
SWOPSIS 

delete  tuple_variable  [where  qual] 

DESCRIPTION 

Delete  removes  tuples  which  satisfy  the  qualification  qua l  from  the  relation  that  they  belong  to. 
The  tuple  variable  must  have  been  declared  to  range  over  an  existing  relation  in  a  picvious 
ranxe  statement.  Delete  docs  not  have  a  rargetjisi.  The  de lew  command  requires  a  tuple  vari¬ 
able  from  a  range  statement,  and  not  the  actual  relation  name.  If  the  qualification  is  not  given, 
the  effect  is  to  delete  all  tuples  in  the  relation.  The  result  is  a  valid,  but  empty  relation 

To  delete  tuples  from  a  relation,  you  must  be  the  owner  of  the  relation,  or  have  delete  permis¬ 
sion  on  the  relation. 

EXAMPLE 

/*  Remove  all  employees  who  make  over  $30,000  */ 
range  of  e  is  emp 
delete  e  where  e.sal  >  30000 

SF.E  ALSO 

destroy(quel),  permit(quel),  quel(quel),  range(quel) 
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DfcSlKo*  tgutL  > 


SAMI'. 

destroy  -  destroy  existing  reiation(s) 

SX  NOPSIS 

destroy  relname  (,  relname! 

destroy  (permit )  integrity]  relname  [integer  (,  integer})  all] 

DESCRIPTION 

Destroy  removes  relations  from  the  data  base,  and  removes  constraints  or  permissions  from  a 
relation.  Only  the  relation  owner  may  destroy  a  relation  or  its  permissions  and  integrity  con¬ 
straints,  A.  relation  may  be  emptied  of  tuples,  but  not  destroyed,  using  the  delete  statement  or 
the  modify  statement. 

If  the  relation  being  destroyed  has  secondary  indices  on  it,  the  secondary  indices  are  also  des¬ 
troyed.  Destruction  of  just  a  secondary  index  does  not  affect  the  primary  relation  it  indexes. 

To  destroy  individual  permissions  or  constraints  for  a  relation,  the  integer  arguments  should  be 
those  printed  by  a  help  permit  (for  destroy  permit)  or  a  help  integrity  (for  destroy  integrity) 
on  the  same  relation.  To  destroy  all  constraints  or  permissions,  the  all  keyword  may  be  used  in 
place  of  individual  integers.  To  destroy  constraints  or  permissions,  either  the  integer  arguments 
or  the  all  keyword  must  be  present. 

EXAMPLE 

/*  Destroy  the  emp  relation  •/ 
destroy  emp 
destroy  emp,  parts 

/*  Destroy  some  permissions  on  parts,  and  all  integrity 
*  constraints  on  employee 

•/ 

destroy  permit  parts  0,  4,  5 
destroy  integrity  employee 

SEE  ALSO 

create(quel),  delete(quel),  help(quel),  index(quel),  modify(quel) 


mmyriii. ) 
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MMI 


Ik* Ip  gel  information  about  how  to  use  im.kis  or  about  relations  in  the  database. 


SA  \OFMS 

help  [  reiname!  ("section" 
help  view  (ret name  !, 
help  protect  1  reiname  |, 
help  integrity  (reiname 


reiname)  |,  “section" 


reiname)) 

.  lelnamcl! 


DESCRIPTION 

Help  may  be  used  to  obtain  sections  of  this  manual,  information  on  the  content  of  the  current 
data  base,  information  about  specific  relations  in  the  data  base,  view  definitions,  or  protection 
and  integrity  constraints  on  a  relation  The  legal  forms  are  as  follow: 

help  "seetion  "  —  Produces  a  copy  of  the  specified  section  of  the  INGRIS  Reference  Manual,  and 
prints  it  on  the  standard  output  device. 

help  -  Gives  information  about  all  relations  that  exist  in  the  current  database, 
help  reiname  {.  relnanw)  —  Gives  information  about  the  specified  relations, 
help  ""  —  Gives  the  table  of  contents. 

help  view  reiname  {.  reiname]  -  Prints  view  definitions  of  specified  views, 
help  protect  reiname  reiname I  —  Prints  permissions  on  specified  relations. 


help  integrity  reiname  {,  reiname)  —  Prints  integrity  constraints  on  specified  relations. 


The  protect  and  integrity  forms  print  out  unique  identifiers  for  each  constraint, 
identifiers  may  be  used  to  remove  the  constraints  with  the  destroy  statement. 


These 


IA  AMPLE 

help 

help  help  /•  prints  this  page  of  the  manual  */ 
help  quel 
help  emp 

help  emp,  parts,  "help",  supply 
help  view  overp  view 
help  protect  parts,  employee 
help  integrity  pans,  employee 


sty  Ai  so 

destroy(quel) 


BIGS 


Alphabetic^  appearing  within  the  section  name  must  be  in  lower-case  to  be  recognized. 
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\  wu. 

index  -  create  a  secondary  index  on  an  existing  relation. 
synopsis 

index  on  relname  is  indexname  (domain  /  l  ,domain2)) 

DESCRIPTION 

Index  is  used  to  create  secondary  indices  on  existing  relations  in  order  to  make  retrieval  and  up¬ 
date  with  secondary  keys  more  efficient.  The  secondary  key  is  constructed  from  relname 
domains  1,  2 . 6  in  the  order  given.  Only  the  owner  of  a  relation  is  allowed  to  create  secon¬ 

dary  indices  on  that  relation. 

In  order  to  maintain  the  integrity  of  the  index,  users  will  NOT  be  allowed  to  directly  update 
secondary  indices.  However,  whenever  a  primary  relation  is  changed,  its  secondary  indices  will 
be  automatically  updated  by  the  system.  Secondary  indices  may  be  modified  to  further  increase 
the  access  efficiency  of  the  primary  relation.  When  an  index  is  first  created,  it  is  automatically 
modified  to  an  isam  storage  structure  on  all  its  domains.  If  this  structure  is  undesirable,  the 
user  may  override  the  default  isam  structure  by  using  the  — n  switch  (see  ingres(unix)),  or  by 
entering  a  modify  command  directly. 

If  a  modify  or  destroy  command  is  used  on  relname ,  all  secondary  indices  on  relname  are  des¬ 
troyed. 

Secondary  indices  on  other  indices,  or  on  system  relations  are  forbidden. 

EXAMPLE 

/*  Create  a  secondary  index  called  ‘V’  on  relation  “emp"  */ 
index  on  emp  is  x(mgr,sal) 


>EE  ALSO 

eopy(quel),  destroy  (quel),  modify(quel) 

BIOS 

At  most  6  domains  may  appear  in  the  key. 

The  copy  command  cannot  be  used  to  copy  into  a  relation  which  has  secondary  indices. 

The  default  structure  isam  is  a  poor  choice  for  an  index  unless  the  range  of  retrieval  is  small. 


*  1  - 
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ntcgrity  -  define  integrity  constraints 


NOPSIS 

define  integrity  on  var  is  qua! 

DESCRIPTION 

The  integrity  statement  add.  an  integrity  constraint  for  the  relation  specified  by  var.  After  the 
constraint  is  placed,  all  updates  to  the  relation  must  satisfy  qua!.  Qua /  must  be  true  when  the 
integrity  statement  is  issued  or  else  a  diagnostic  is  issued  and  the  statement  is  rejected. 

In  the  current  implementation,  integrity  constraints  are  not  flagged  -  bad  updates  are  simply 
(and  silently)  not  performed. 

Qua!  must  be  a  single  variable  qualification  and  may  not  contain  any  aggregates. 

integrity  statement  may  be  issued  only  by  the  relation  owner. 

EXAMPLE 

/*  Ensure  all  employees  have  positive  salaries  */ 
range  of  e  is  employee 
define  integrity  on  e  is  e. salary  >  0 


SEF  \ISO 

destroy(quel) 


v 
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NAME 

macros  —  terminal  monitor  macro  facility 

DESCRIPTION 

The  terminal  monitor  macro  facility  provides  the  ability  to  tailor  the  QUEL  language  to  the 
user’s  tastes.  The  macro  facility  allows  strings  of  text  to  be  removed  from  the  query  stream 
and  replaced  with  other  text.  Also,  some  built  in  macros  change  the  environment  upon  execu¬ 
tion. 

Basic  Concepts 

All  macros  are  composed  of  two  parts,  the  template  part  and  the  replacement  part.  The  template 
part  defines  when  the  macro  should  be  invoked.  For  example,  the  template  "ret"  causes  the 
corresponding  macro  to  be  invoked  upon  encountering  the  word  “ret”  in  the  input  stream. 
When  a  macro  is  encountered,  the  template  part  is  removed  and  replaced  with  the  replacement 
part.  For  example,  if  the  replacement  part  of  the  “ret"  macro  was  '‘retrieve",  then  ail  in¬ 
stances  of  the  word  “ret"  in  the  input  text  would  be  replaced  with  the  word  “retrieve",  as  in 
the  statement 

ret  (p.all) 

Macros  may  have  parameters,  indicated  by  a  dollar  sign.  For  example,  the  template  “get  SI" 
causes  the  macro  to  be  triggered  by  the  word  “gel"  followed  by  any  other  word.  The  word  fol¬ 
lowing  “get"  is  remembered  for  later  use.  For  example,  if  the  replacement  part  of  the  “get" 
macro  where 

retrieve  (p.all)  where  p.pnum  =  SI 

then  typing  “get  35"  would  retrieve  all  information  about  part  number  35. 

Defining  Macros 

Macros  can  be  defined  using  the  special  macro  called  “define".  The  template  for  the  define 
macro  is  (roughly) 

(define;  St;  Sr) 

where  St  and  Sr  are  the  template  and  replacement  parts  of  the  macro,  respectively. 

Let’s  look  at  a  few  examples.  To  define  the  “ret"  macro  discussed  above,  we  would  type: 
(define;  ret;  retrieve) 

When  this  is  read,  the  macro  processor  removes  everything  between  the  curly  braces  and  up¬ 
dates  some  tables  so  that  “ret"  will  be  recognized  and  replaced  with  the  word  “retrieve".  The 
define  macro  has  the  null  string  as  replacement  text,  so  that  this  macro  seems  to  disappear. 

A  useful  macro  is  one  which  shortens  range  statements.  It  can  be  defined  with 

(define;  rg  $v  Sr;  range  of  Sv  is  Srj 

This  macro  causes  the  word  “rg"  followed  by  the  next  two  words  to  be  removed  and  replaced 
by  the  words  “range  of",  followed  by  the  first  word  which  followed  “rg”,  followed  by  the  word 
“is",  followed  by  the  second  word  which  followed  “rg".  For  example,  the  input 

rg  p  parts 

becomes  the  same  as 

range  of  p  is  parts 

Evaluation  Times 

When  you  type  in  a  define  statement,  it  is  not  processed  immediately,  just  as  queries  are  saved 
rather  than  executed  No  macro  processing  is  done  until  the  query  buffer  is  evaluated  The 
commands  \go.  Mist,  and  \evul  evaluate  the  query  bufTcr.  \go  sends  the  results  to  im.ri  s.  list 
prints  them  on  your  terminal,  and  \eval  puts  the  result  back  into  the  query  buffer 
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It  is  important  u>  evaluate  arts  define  statements,  or  it  will  be  exactly  like  you  did  i . •  u  type  them 
in  .it  all  \  common  wa>  to  define  macros  is  to  type 

[define  .  .  .  ! 

\eval 
\ reset 

IT  the  \eval  was  left  out.  there  is  no  effect  at  all. 

Quoting 

Sometimes  strings  must  be  passed  through  the  macro  processor  without  being  processed.  In 
such  eases  the  grave  and  acute  accent  marks  C  and  ')  can  be  used  to  surround  the  literal  text. 
For  example,  to  pass  the  word  “ret"  through  without  converting  it  to  ‘"retrieve"  we  could  type 

'ret' 

Another  use  for  quoting  is  during  parameter  collection.  If  we  want  to  enter  more  than  one 
word  w'here  only  one  was  expected,  we  can  surround  the  parameter  with  accents. 

The  backslash  character  quotes  only  the  next  character  (like  surrounding  the  character  with  ac¬ 
cents).  In  particular,  a  grave  accent  can  be  used  literally  by  proceeding  it  with  a  backslash 

Since  macros  can  normally  only  he  on  one  line,  it  is  frequently  useful  to  use  a  backslash  at  the 
end  of  the  line  to  hide  the  newline.  For  example,  to  enter  the  long  “get"  macro,  you  might 
type: 

[define;  get  $n;  retrieve  le.all)  \ 
where  e.name  *  "Sn”) 

The  backslash  always  quotes  the  next  character  even  w'hen  it  is  a  backslash.  So,  to  get  a  real 
backslash,  use  two  backslashes. 

More  Parameters 

Parameters  need  not  be  limited  to  the  word  following.  For  example,  in  the  template  descriptor 
for  define: 

{define;  St;  Sr  I 

the  St  parameter  ends  at  the  first  semicolon  and  the  Sr  parameters  ends  at  the  first  right  curly 
brace.  The  rule  is  that  the  character  which  follows  the  parameter  specifier  terminates  the 
parameter;  if  this  character  is  a  space,  tab,  newline,  or  the  end  of  the  template  then  one  word  is 
collected. 

As  with  all  good  rules,  i h i s  one  has  an  exception.  Since  system  macros  are  always  surrounded 
by  curly  braces,  the  macro  processor  knows  ihat  they  must  be  properly  nested.  Thus,  in  the 
statement 

{define;  x;  jsysfnl) 

The  first  right  curly  brace  will  close  the  “sysl’n"  rather  than  ihe  “define"  Otherwise  this 
would  have  to  be  typed 

[define;  x;  *[s>sfn|,| 

Words  arc  defined  m  the  usual  way.  as  strings  of  letters  and  digits  plus  the  underscore  charac¬ 
ter. 

Other  Builtin  Macros 

There  are  several  other  macros  built  in  to  the  macro  processor  In  the  following  description, 
some  of  the  parameter  specifiers  arc  marked  with  two  dollar  signs  rather  than  one;  this  will  be 
discussed  in  the  section  on  prescanning  below. 

'define,  SSt:  SSrj  defines  a  macro  as  discussed  above.  Special  processing  occurs  on  the  template 
part  which  will  be  discussed  in  a  later  section. 
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[rawdefine;  SSt;  SSri  is  another  form  of'  define,  where  the  special  processing  does  not  take 
place. 

[remove;  $$n|  removes  the  macro  with  name  Sn.  It  can  remove  more  than  one  macro,  since  it 
actually  removes  all  macros  which  might  conflict  with  Sn  under  some  circumstance.  For  exam¬ 
ple,  typing 

[define;  get  part  Sn;  .  .  .  ) 

[define;  get  emp  Sx;  .  .  .  | 

[remove;  getj 

would  cause  both  the  get  macros  to  be  removed.  A  call  to 
[remove;  get  part} 

would  have  only  removed  the  first  macro. 

[type  S$s)  types  $s  onto  the  terminal. 

[read  SSs}  types  Ss  and  then  reads  a  line  from  the  terminal.  The  line  which  was  typed  replaces 
the  macro.  A  macro  called  “[readcountp  is  defined  containing  the  number  of  characters  read. 
A  control-D  (end  of  file)  becomes  -1,  a  single  newline  becomes  zero,  and  so  forth. 

[readdefine;  $$n;  $$s}  also  types  $s  and  reads  a  line,  but  puts  the  line  into  a  macro  named  Sn. 
The  replacement  text  is  the  count  of  the  number  of  characters  in  the  line,  [readcountj  is  still 
defined. 

[ifsame;  $$a;  SSb;  St;  $f)  compares  the  strings  Sa  and  Sb.  If  they  match  exactly  then  the  re¬ 
placement  text  becomes  Si,  otherwise  it  becomes  Sf. 

[ifeq:  SSa;  SSb;  St;  Sf}  is  similar,  but  the  comparison  is  numeric. 

iifgt;  SSa;  SSb;  Si;  Sf)  is  like  ifeq,  but  the  test  is  for  Sa  strictly  greater  than  Sb. 

[subsir;  SSf;  SSt;  SSs}  returns  the  part  of  Ss  between  character  positions  Sf  and  St,  numbered 
from  one.  If  Sf  or  St  are  out  of  range,  they  are  moved  in  range  as  much  as  possible. 

[dump;  SSn}  returns  the  value  of  the  macro  (or  macros)  which  match  Sn  (using  the  same  algo¬ 
rithm  as  remove).  The  output  is  a  rawdefine  statement  so  that  it  can  be  read  back  in.  [dump} 
without  arguments  dumps  all  macros. 

Metacharacters 

Certain  characters  are  used  internally.  Normally  you  will  not  even  see  them,  but  they  can  ap¬ 
pear  in  the  output  of  a  dump  command,  and  can  sometimes  be  used  to  create  very  fancy  mac¬ 
ros. 

|  matches  any  number  of  spaces,  tabs,  or  newlines.  It  wil)  even  match  zero,  but  only  between 
words,  as  can  occur  with  punctuation.  For  example,  \|  will  match  the  spot  between  the  last 
character  of  a  word  and  a  comma  following  it. 

matches  exactly  one  space,  lab,  or  newline. 

&  matches  exactly  zero  spaces,  tabs,  or  newlines,  but  only  between  words. 

The  Define  Process 

W  hen  you  define  a  macro  using  define,  a  lot  of  special  processing  happens.  This  processing  is 
such  that  define  is  not  functionally  complete,  hut  still  adequate  for  most  requirements.  If  more 
power  is  needed,  rawdefine  can  be  used;  however,  rawdefine  is  particularly  difficult  to  use 
correctly,  and  should  only  he  used  by  gurus 

In  define,  all  sequences  of  spaces,  tabs,  and  now  lines  in  the  template,  as  well  as  all  non* 
spaces' '  between  words,  are  turned  into  a  single  \|  character.  II  the  template  ends  with  a 
parameter,  the  \&  character  is  added  at  (he  end. 

If  you  want  to  match  a  real  tab  or  newline,  you  can  use  \t  or  \n  respectively.  For  example,  a 
macro  which  reads  an  entire  line  and  uses  it  as  the  name  of  an  employee  would  be  defined  with 
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i define;  get  Sn\n;  \ 

ret  (call)  where  e. name  =■  "$n"i 

This  macro  might  he  used  b>  typing 

get  *Stan* 

to  get  all  information  about  everyone  with  a  name  which  included  "Stan".  By  the  way,  notice 
that  it  is  ok  to  nest  the  “ret*'  macro  inside  the  “get"  macro. 

Parameter  Prescan 

Sometimes  it  is  useful  to  macro  process  a  parameter  before  using  it  in  the  replacement  part 
This  is  particularly  important  when  using  certain  buiitin  macros. 

For  prescan  to  occur,  two  things  must  he  true:  first,  the  parameter  must  be  specified  in  the 
template  with  two  dollar  signs  instead  of  one,  and  second,  the  actual  parameter  must  begin  with 
an  “at"  sign  (“@“)  (which  is  stripped  off). 

For  an  example  of  the  use  of  p rescan,  sec  “Special  Macros"  below. 

Special  Macros 

Some  special  macros  are  used  by  the  terminal  monitor  to  control  the  environment  and  return 
results  to  the  user. 

(begintrap)  is  executed  at  the  beginning  of  a  query. 

(endtrapj  is  executed  after  the  body  of  a  query  is  passed  to  INGRES. 

jeontinuetrap}  is  executed  after  the  query  completes.  The  difference  between  this  and  endtrap 
is  that  endtrap  occurs  after  the  query  is  submitted,  but  before  the  query  executes,  whereas  com 
tinuetrap  is  executed  after  the  query  executes. 

{editor)  can  be  defined  to  be  the  pathname  of  an  editor  to  use  in  the  \edil  command. 

{shell }  can  be  defined  to  be  the  pathname  of  a  shell  to  use  in  the  \shell  command. 

{luplccountj  is  set  after  every  query  (but  before  conlinuetrap  is  sprung)  to  be  the  count  of  the 
number  of  tuples  which  satisfied  the  qualification  of  the  query  in  a  retrieve,  or  the  number  of 
tuples  changed  in  an  update.  It  is  not  set  for  DBU  functions.  If  multiple  queries  are  run  at 
once,  it  is  set  to  the  number  of  tuples  which  satisfied  the  last  query  run. 

For  example,  to  prim  out  the  number  of  tuples  touched  auu  maticaliy  after  each  query,  you 
could  enter: 

{define;  {begintrap);  {remove;  {tuplccounijli 
{define;  {continue! rap):  \ 

{ifsame;  @ {tuplecountl;  {luplccouni};;  \ 

{type  @!tuplecount|  tuples  touched) {} 

SET.  ALSO 

monitor(quel) 
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NAME 

modify  -  convert  the  storage  structure  of  a  relation 

sx  NOPSIS 

modify  relname  to  storage-structure  [  on  kevl  [  :  soriorder  1  (  {  *  key2  (  :  sortordvr  1)111 

where  [  fillfactor  =  //][♦  minpages  =  //]!,  maxpages  =  //  1  ) 


DESCRIPTION 

Rebtanw  is  modified  to  the  specified  storage  structure.  Only  the  owner  of  a  relation  can  modify 
that  relation.  This  command  is  used  to  increase  performance  when  using  large  or  frequently 
referenced  relations  The  storage  structures  are  specified  as  follows 

isam  -  indexed  sequential  storage  structure 

eisam  —  compressed  isam 

hash  —  random  hah  storage  structure 

chash  —  compressed  hash 

heap  -  unkeyed  and  unstructured 

cheap  —  compressed  heap 

heapsort  -  heap  with  tuples  sorted  and  duplicates  removed 
cheapsort  —  compressed  heapsort 
truncated  -  heap  with  all  tuples  deleted 

The  paper  “Creating  and  Maintaining  a  Database  in  INGRES"  (ERL  Memo  M77  — 71)  discusses 
how  to  select  storage  structures  based  on  how  the  relation  is  used. 

The  current  compression  algorithm  only  suppresses  trailing  blanks  in  character  fields.  A  more 
effective  compression  scheme  may  be  possible,  but  tradeoffs  between  that  and  a  larger  and 
slower  compression  algorithm  are  not  clear. 

If  the  on  phrase  is  omitted  when  modifying  to  isam,  cisam,  hash  or  chash,  the  relation  will  au¬ 
tomatically  be  keyed  on  the  first  domain.  When  modifying  to  heap  or  cheap  the  on  phrase  must 
be  omitted.  When  modifying  to  heapsort  or  cheapsort  the  on  phrase  is  optional. 

When  a  relation  is  being  sorted  (isam,  cisam.  heapsort  and  cheapsort),  the  primary  sort  keys 
will  be  those  specified  in  the  on  phrase  (if  any).  The  first  key  after  the  on  phrase  will  be  the 
most  significant  sort  key  and  each  successive  key  specified  will  be  the  next  most  significant  sort 
key.  Any  domains  not  specified  in  the  on  phrase  will  be  used  as  least  significant  sort  keys  in 
domain  number  sequence. 

When  a  relation  is  modified  to  heapsort  or  cheapsort,  the  sortorder  can  be  specified  to  be  as¬ 
cending  or  descending.  The  default  is  always  ascending.  Each  key  given  in  the  on  phrase  can 
be  optionally  modified  to  be: 

key.descending 

which  will  cause  that  key  to  be  sorted  in  descending  order.  For  completeness,  ascending  can 
be  specified  after  the  colon  (':'),  although  this  is  unnecessary  since  it  is  the  default.  Descend¬ 
ing  can  be  abbreviated  by  a  single  d'  and,  correspondingly,  ascending  can  be  abreviated  b\  a 
single  ‘a'. 

htltdi tor  specifics  the  percentage  (from  1  to  100)  of  each  primary  data  page  that  should  be  filled 
with  tuples,  under  ideal  conditions,  htllfaiior  may  be  used  with  isam.  cisam,  hash  and  chash. 
(  are  should  be  taken  when  using  large  lillfuctors  since  a  non-uniform  distribution  of  ke>  \alues 
could  cause  overflow  pages  lo  be  created,  and  thus  degrade  access  performance  for  the  relation. 

MtnfHWs  specifies  the  minimum  number  of  primary  pages  a  hash  or  chash  relation  must  have 
Afi/.xpuvo  specifies  the  maximum  number  of  primary  pages  a  hash  or  chash  relation  max  have 
A/ui/wa'i’.v  and  ma.\pa i,v\  must  he  at  least  one.  If  both  minpuges  and  maxpages  are  specified  in  a 
modifv,  minpages  cannot  exceed  maxpages. 

Default  values  for  fillfactor.  minpages,  and  maxpages  are  us  follows 
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///./  /  K  !()K 

VIS  PAGES 

MAX  PAULS 

hash 

50 

10 

no  limit 

chash 

75 

1 

no  limit 

isam 

80 

NA 

NA 

cisam 

100 

NA 

NA 

EXAMPLES 

I*  modify  the  emp  relation  to  an  indexed 
sequential  storage  structure  with 
"name”  as  the  keyed  domain  V 

modify  emp  to  isum  on  name 

/*  if  "name"  is  the  first  domain  of  the  emp  relation, 
the  same  result  can  be  achieved  by  */ 

modify  emp  to  isam 

/*  do  the  same  modify  but  request  a  60%  occupancy 
on  all  primary  pages  V 

modify  emp  to  isam  on  name  where  fillfactor  =  60 

/*  modify  the  supply  relation  to  compressed  hash 
storage  structure  with  "num"  and  "quan" 
as  keyed  domains  V 

modify  supply  to  chash  on  num.  quan 

/*  now  the  same  modify  but  also  request  75°/..  occupancy 
on  ail  primary,  a  minimum  of  7  primary  pages 
pages  and  a  maximum  of  43  primary  pages  V 

modify  supply  to  chash  on  num,  quan 

where  fillfactor  =  75,  minpages  =  7, 
maxpages  =  43 

f*  again  the  same  modify  but  only  request  a  minimum 
of  16  primary  pages  V 

modify  supply  to  chash  on  num,  quan 
where  minpages  =  16 

/*  modify  parts  to  a  heap  storage  structure  */ 

modify  parts  to  heap 

/*  modif>  parts  to  a  heap  again,  but  have  tuples 

sorted  on  "pmim"  domain  and  have  any  duplicate 
tuples  removed  */ 

moilify  parts  to  heupsnrl  on  pnum 

r  modify  employee  in  ascending  order  by  manager, 
descending  order  by  salary  and  have  an\ 
duplicate  tuples  removed  */ 

modify  employee  to  heapsort  on  manager.  salary:descending 


\  K  \l  SO 

sysmod(unix) 
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NAME 

monitor  —  interactive  terminal  monitor 
DESCRIPTION 

The  interactive  terminal  monitor  is  the  primary  front  end  to  iMikis.  it  provides  the  ability  to 
formulate  a  query  and  review  it  before  issuing  it  to  INGRES.  If  changes  must  be  made,  one  of 
the  UNIX  text  editors  may  be  called  to  edit  the  query  buffer. 

Messages  and  Prompts. 

The  terminal  monitor  gives  a  variety  of  messages  to  keep  the  user  informed  of  the  status  of  the 
monitor  and  the  query  buffer. 

As  the  user  logs  in,  a  login  message  is  printed.  This  typically  tells  the  version  number  and  the 
login  time.  It  is  followed  by  the  dayfile,  which  gives  information  periinant  to  users. 

When  INGRES  is  ready  to  accept  input,  the  message  ”go"  is  printed.  This  means  that  the  query 
buffer  is  empty.  The  message  'continue*'  means  that  there  is  information  in  the  query  buffer. 
After  a  \go  command  the  query  buffer  is  automatically  cleared  if  another  quer\  is  typed  in.  un¬ 
less  a  command  which  affects  the  query  buffer  is  typed  first.  These  commands  are  \append. 
\ediu  \prinl,  \list,  \evaL  and  \go.  Lor  example,  typing 
help  parts 
\go 

print  parts 

results  in  the  query  buffer  containing 

print  parts 

whereas 

help  parts 
\go 
\print 
print  parts 

results  in  the  query  buffer  containing 
help  parts 
print  parts 

An  asterisk  is  printed  at  the  beginning  of  each  line  when  the  monitor  is  wailing  for  the  user  to 
type  input. 

Commands 

There  are  a  number  of  commands  which  may  be  entered  by  the  user  to  affect  the  query  buffer 
or  the  user's  environment.  They  are  all  preceeded  by  a  backslash  TV),  and  all  are  executed 
immediately  (rather  than  at  execution  lime  like  queries). 

Some  commands  may  take  a  filename,  which  is  defined  as  the  first  significant  character  after  the 
end  of  the  command  until  the  end  of  the  line.  These  commands  may  have  no  other  commands 
on  the  line  with  them.  Commands  which  do  not  take  a  filename  may  be  stacked  on  the  line; 
for  example 

\dale\go\date 

will  give  the  time  before  and  after  execution  of  the  current  query  buffer. 

\r 

\reset  Erase  the  entire  query  (reset  the  query  buffer).  The  former  contents  of  the  buffer 
are  irretrieveably  lost. 

\p 

\pnnt  Print  the  current  query.  The  contents  of  the  bufler  are  printed  on  the  user  s  termi¬ 
nal. 

\l 

\lisi  Print  the  current  query  as  it  will  appear  after  macro  processing.  Any  side  effects  ol 

macro  processing,  such  as  macro  definition,  will  occur. 
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eval  Macro  process  ihe  query  butler  and  replace  the  query  buffer  with  the  result.  This  is 
jusi  like  Mist  except  that  the  output  is  put  into  the  query  butler  instead  of  to  the  ter¬ 
minal 

\e 

\cd 

\edit 

\editor  Enter  the  t  M\  text  editor  (see  ED  in  the  i  MX  Programmer's  Manual);  use  the  ED 
command  'w*  followed  by  V  l<>  return  to  the  Ingres  monitor.  If  ..  filename  is 
given,  the  editor  is  called  with  that  file  instead  of  the  query  buffer  If  the  '.aero 
“[editor!"  is  defined,  that  macro  is  used  as  the  pathname  of  an  editor,  otherwise 
“/bin/ed"  is  used.  It  is  important  that  you  do  not  use  the  V  command  inside  the 
editor;  if  >ou  do  the  (obscure)  name  of  the  query  buffer  will  be  forgotten 

\g 

\go  Process  the  current  query.  The  contents  of  the  buffer  are  macro  processed, 

transmitted  to  INGRES,  and  run. 

\a 

\append  Append  to  the  query  buffer.  Typing  \a  after  completion  of  a  query  will  override  the 
auto-clear  feature  and  guarantees  that  the  query  buffer  will  not  be  reset. 

\time 

\date  Print  out  the  current  lime  of  day. 

\s 

\sh 

\shell  Escape  to  the  (  MX  shell.  Typing  a  control-d  will  cause  you  to  exit  the  shell  and  re¬ 
turn  to  the  Ingres  monitor.  If  there  is  a  filename  specified,  that  filename  is  taken  as 
a  shell  file  which  is  run  with  the  query  buffer  as  the  parameter  "SI”.  If  no  filename 
is  given,  an  interactive  shell  is  forked.  If  the  macro  “[shell)"  is  defined,  it  is  used 
as  the  pathname  of  a  shell;  otherwise,  “/bin/sh"  is  used. 

\d 

\quit  Exit  from  INGRES. 

\cd 

\chdir  Change  the  working  directory  of  the  monitor  to  the  named  directory. 

\i 

\include 

\read  Switch  input  to  the  named  file.  Backslash  characters  in  the  file  will  be  processed  as 
read. 

\w 

\write  Write  the  contents  of  the  query  buffer  to  the  named  file. 

\branch  Transfer  control  within  a  \includc  file.  See  the  section  on  branching  below 
\mark  Set  a  label  for  \branch. 

\<am  other  character > 

Ignore  any  possible  special  meaning  of  character  following  ‘  '.  This  allows  the  '  *  to 
be  input  as  a  literal  character.  (See  also  qiicl(qucl)  -  strings),  h  is  important  to 
note  that  backslash  escapes  are  sometimes  eaten  up  In  the  macro  processor  also;  in 
general,  send  two  backslashes  if  you  want  a  backslash  sent  (even  this  is  too  simplis¬ 
tic  [sigh]  -  try  to  avoid  using  backslashes  at  all). 

X  fiicr  os 

I  or  simplicity,  the  macros  are  described  in  the  section  macros(quel L 

Branching 

Ihe  branch  and  \mark  commands  permit  arbitrary  branching  within  a  'include  file  (similar  to 
the  goto"  and  commands  in  the  shell),  \mark  should  be  followed  with  a  label  hunch 
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should  ho  lolloped  with  either  a  label,  indicating  unconditional  branch,  or  an  expression  pro* 
ceeded  b\  a  question  mark,  lolloped  b>  a  label,  indicating  a  conditional  branch  The  branch  is 
taken  if  the  expression  is  greater  than  zero  \  or  example, 

\brunch  ?ituplceouni)  <  -0  nolups 

branches  to  label  "nolups'*  it'  ihe  "Ituplecouml"  macro  is  less  than  or  equal  to  zero 

The  expressions  usable  in  \branch  statements  arc  somewhat  restricted  The  operators  + 

/,  <=.  >**,  <,  >.  =  ,  and  !=  are  all  defined  in  the  expected  way.  The  left  unary  operator 
"!"  can  be  used  as  to  indicate  logical  negation.  There  may  be  no  spaces  in  the  expression, 
since  a  space  terminates  the  expression. 

Initialization 

At  initialization  (login)  time  a  number  of  initializations  take  place.  First,  a  macro  called  “ [path¬ 
name}"  is  defined  which  expands  to  the  pathname  of  the  inukis  subtree  (normally 
"/mni/ingres");  it  is  used  by  system  routines  such  as  demodb  Second,  the  initialization  file 
.../files/starlup  is  read.  This  file  is  intended  to  define  system-dependent  parameters,  such  as 
the  default  editor  and  shell.  Third,  a  user  dependent  initialization  file,  specified  by  a  field  in 
the  users  lile.  is  read  and  executed.  This  is  normally  set  (o  the  file  \ingres"  in  the  user's 
home  directory.  The  startup  file  might  be  used  to  define  certain  macros,  execute  common 
range  statements,  and  soforth.  Finally,  control  is  turned  over  to  the  user's  terminal. 

An  interrupt  while  executing  either  of  the  initialization  files  restarts  execution  of  that  step. 

Flags 

Certain  flags  may  be  included  on  the  command  line  to  ingris  which  affect  the  operation  of  the 
terminal  monitor.  The  ~a  flag  disables  the  autoclear  function.  This  means  that  the  query 
buffer  will  never  be  automatically  cleared;  equivalently,  it  is  as  though  a  \append  command 
were  inserted  after  every  \go.  Note  that  this  means  that  the  user  must  explicitly  clear  the  query 
buffer  using  \reset  after  every  query.  The  -d  flag  turns  off  the  printing  of  the  dayfile.  The  -s 
flag  turns  off  printing  of  all  messages  (except  errors)  from  the  monitor,  including  the  login  and 
logout  messages,  the  dayfile,  and  prompts.  It  is  used  for  executing  "canned  queries'*,  that  is, 
queries  redirected  from  files. 

sn  xt.so 

mgres(unix),  quel(quel),  mucros(quel) 


01  \(,\()ST1(  S 
go 

continue 

Executing 

>  >ed 

>  >sh 


You  may  begin  a  fresh  query. 

The  previous  query  is  finished  and  you  are  back  in  the  monitor. 
The  query  is  being  processed  by  INGRtiS. 

You  have  entered  the  UNIX  text  editor. 

You  have  escaped  to  the  UNIX  shell. 


Funny  character  nnn  converted  to  blank 

INC  *  H  is  maps  non-printing  ASCII  characters  into  blanks;  this  message  in¬ 
dicates  that  one  such  conversion  has  just  been  made. 


IM  OMPVIIBIl  rms 

Note  that  the  construct 

\rprint  parts 

(intended  to  reset  the  query  buffer  and  then  enter  "print  parts")  no  longer  works,  since  "rprint" 
appears  to  be  one  word. 


F 


\  PRINT  ( QUHL  >  1/26/79  PRINK QUIT.) 

I 

! 


\  \MK 

print  ~  print  relation(s) 
s\  nopsis 

print  iclname  i,  reinamcl 


ms(  rum  ion 

Print  displays  the  contents  of  each  relation  specified  on  the  terminal  (standard  output).  The 
formats  for  various  types  of  domains  can  be  defined  by  the  use  of  switches  when  inures  is  in¬ 
voked.  Domain  names  are  truncated  to  fit  into  the  specified  width. 

To  print  a  relation  one  must  either  be  the  owner  of  the  relation,  or  the  relation  must  have  "re¬ 
trieve  to  all"  or  "all  to  all"  permissions. 

See  ingres(quel)  for  details. 


EXAMPLE 

/*  Print  the  emp  relation  */ 
print  emp 
print  emp,  parts 


s Ft  Al  so 

permit(quel),  retrieve(quel),  ingres(unix),  printr(unix)  handle  long  lines  of  output  correctly  — 
no  wrap  around. 

Print  should  have  more  formating  features  to  make  printouts  more  readable. 

Print  should  have  an  option  to  print  on  the  line  printer. 
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WMF 

permit  -  add  permissions  to  a  relation 

SN  NOPSIS 

define  permit  oplisl  |  on  l  of  |  to  )  var  [  (alllisi)  I 
to  name  1  at  term  1  [  from  time  to  time  1 
I  on  day  to  day  I  I  where  qual  ) 


DESCRIPTION 

The  permit  staiemeni  extends  the  current  permissions  on  the  relation  specified  by  \ar.  Ophst  is 
a  comma  separated  fist  of*  possible  operations,  which  can  be  retrieve,  replace,  delete,  append, 
or  all;  all  is  a  special  case  meaning  all  permissions.  Same  is  the  login  name  of  a  user  or  the 
word  all  Term  is  a  terminal  name  of  the  form  dty.v'  or  the  keyword  all:  omitting  this  phrase  is 
equivalent  to  specifying  all.  rum's  are  of  the  form  khh;mm'  on  a  twenty-four  hour  clock  which 
limit  the  times  of  the  day  during  which  this  permission  applies.  Days  are  three-character  abbre¬ 
viations  for  days  of  the  week.  The  qua!  is  appended  to  the  qualification  of  the  query  when  it  is 
run 

Separate  parts  of  a  single  permit  statement  are  conjoined  (ANDed).  Different  permit  statements 
are  disjoined  (ORed).  For  example,  if  you  include 

...  to  eric  at  lty4  .  .  . 

the  permit  applies  only  to  eric  when  logged  in  on  tty4,  hut  if  you  include  two  permit  statements 

...  to  eric  at  all  .  .  . 

.  .to  all  at  Uy4  .  .  . 

then  when  eric  logs  in  on  tty4  he  will  get  the  union  of  the  permissions  specified  by  the  two 
statements.  If  eric  logs  in  on  Uyd  he  will  get  only  the  permissions  specified  in  the  first  permit 
statement,  and  if  hob  logs  in  on  1 1 y 4  he  will  get  only  the  permissions  specified  in  the  second 
permit  statment. 

The  permit  statement  may  only  be  issued  by  the  owner  of  the  relation.  Although  a  user  other 
than  the  DBA  may  issue  a  permit  statement,  it  is  useless  because  noone  else  can  access  her  rela¬ 
tions  anyway 

Penmt  statements  do  not  apply  to  the  owner  of  a  relation  or  to  views. 

The  statements 

define  permit  all  on  x  to  all 
define  permit  retrieve  of  \  to  all 

with  no  further  qualification  are  handled  as  special  cases  and  are  thus  particularly  efficient. 
EXAMPLES 

range  of  e  is  employee 

define  permit  retrieve  of  e  (name,  sail  to  marc 
at  it  yd  from  8:00  to  17  00 
on  Mon  to  I:ri 
where  e  mgr  —  "marc" 

range  of  p  is  parts 

define  permit  retrieve  of  e  to  all 


see  \i  so 

destroy  (quel  I 
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quel  Ql  Krv  Language  for  inwri  x 
l)t  X  RIPTION 

The  following  is  a  description  of  the  general  syntax  of  gi  n .  Individual  gi  it  statements  and 
commands  are  treated  separate!}  in  the  document ;  this  section  describes  the  syntactic  classes 
from  which  the  constituent  parts  of  gi  i  t  statements  are  drawn. 

1  Comments 

A  comment  is  an  arbitrary  sequence  of  characters  bounded  on  the  left  by  *7*"  and  on  the  right 
by  •■*/": 

/*  This  is  a  comment  */ 

2  Names 

Names  in  gt  i  l  are  sequences  of  no  more  than  12  alphanumeric  characters,  starting  with  an  al¬ 
phabetic  Underscore  (  )  is  considered  an  alphabetic.  A!)  upper -case  alphabetics  appearing 
anywhere  except  in  strings  are  automatically  and  silently  mapped  into  their  lower-case  coun¬ 
terparts. 

3.  Keywords 

The  following  identifiers  are  reserved  for  use  as  keywords  and  may  not  be  used  otherwise. 


abs 

all 

and 

any 

append 

ascii 

at 

atari 

avg 

avgu 

by 

concat 

copy 

cos 

count 

count  u 

create 

define 

delete 

destroy 

exp 

Hoat4 

HoatK 

from 

gamma 

help 

in 

index 

inti 

int  2 

int4 

integrity 

into 

is 

Ion 

max 

min 

mod 

modify 

not 

of 

on 

onto 

or 

permit 

print 

range 

replace 

retrieve 

save 

sin 

sqrt 

sum 

s  urnu 

to 

unique 

until 

view 

where 

4  Constants 

i  here  are  three  types  of  constants,  corresponding  to  the  three  data  types  as  tillable  m  gi  I  t  tor 
data  storage. 

4  1  String  constants 

Strings  in  gt  1 1  are  sequences  of  no  more  than  255  arbitrary  A  SC  II  characters  bounded  by  dou¬ 
ble  quotes  (  "  "  I  Upper  case  alphabetics  within  strings  are  accepted  literally  Also,  m  order  to 
imbed  quotes  within  strings,  it  is  necessary  to  prelix  them  with  '  ‘  The  Name  consention  ap¬ 
plies  to  'V  itself. 

Only  printing  characters  are  allowed  within  sitings  Non-printing  characters  ti  e  control  chaiac- 
ters)  arc  converted  to  blanks. 
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4  2  Integer  constants 

Integer  constants  m  gm  range  from  -2,147.483,647  to  +2.147.483.647,  Integer  constants 
beyond  that  range  will  be  converted  to  floating  point.  II  the  integer  is  greater  than  32,767  or 
less  than  -32,767  then  it  will  be  left  as  a  two  byte  integer.  Otherwise  it  is  convened  to  a  four 
byte  integer. 

4  3.  Floating  point  constants 

Floating  constants  consist  of  an  integer  pari,  a  decimal  point,  and  a  fraction  part  or  scientific 
notation  of  the  following  formal: 

!  < dig > )  (. < dig> ]  le|E  l+|~l  !  < dig >  II 

Where  <dig>  is  a  digit,  II  represents  zero  or  one,  II  represents  zero  or  more,  and  |  represents 
alternation  An  exponent  with  a  missing  mantissa  has  a  mantissa  of  !  inserted.  There  may  he 
no  extra  characters  embedded  in  the  string.  Floating  constants  are  taken  to  be  double-precision 
quantities  with  a  range  of  approximately  -I0*K  to  10^s  and  a  precision  of  17  decimal  digits 

5.  Attributes 

An  attribute  is  a  construction  of  the  form: 
variable. domain 

\  arui hie  identifies  a  particular  relation  and  can  be  thought  of  as  standing  for  the  rows  or  tuples 
of  that  relation.  A  variable  is  associated  with  a  relation  by  means  of  a  range  statement.  Domain 
is  the  name  of  one  of  the  columns  of  the  relation  over  which  the  variable  ranges.  Together 
they  make  up  an  attribute,  which  represents  values  of  the  named  domain. 

6.  Arithmetic  operators 

Arithmetic  operators  take  numeric  type  expressions  as  operands.  Unary  operators  group  right 
to  left;  binary  operators  group  left  to  right.  The  operators  (in  order  of  descending  precedence) 
are: 

+  (unary)  plus,  minus 

**  exponentiation 

*,/  multiplication,  division 

+  (binary)  addition,  subtraction 

Parentheses  may  be  used  for  arbitrary  grouping.  Arithmetic  overflow  and  divide  by  zero  are 
not  cheeked  on  integer  operations.  Floating  point  operations  are  cheeked  for  overflow, 
underflow,  and  divide  by  zero  only  if  (he  appropriate  machine  hardware  exists  and  has  been  en¬ 
abled. 

7.  Expressions  (a  expr) 

An  expression  is  one  of  the  following: 

constant 

attribute 

functional  expression 
aggregate  or  aggregate  function 

a  combination  of  numeric  expressions  and  arithmetic  operators 

For  the  purposes  of  this  document,  an  arbitrary  expression  will  he  refered  to  by  the  name 
a  e\pr. 

8  Formats 

I  very  a  e\pt  has  a  formal  denoted  b>  a  letter  <c,  i,  or  f,  for  character,  integer,  or  floating  data 
types  respectively)  and  a  number  indicating  the  number  of  bytes  of  storage  occupied.  Formats 
currently  supported  are  listed  below.  The  ranges  of  numeric  types  arc  indicated  in  parentheses 
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cl  -  c2>5  character  data  of  length  I  - 255  characters 

11  I -byte  integer  (  128  lu  4  127) 

1 2  2-bue  integer  (-  32768  to  +32767) 

i4  4-byte  integer  (-2 ,147,483,648  to  +2,147,483,647) 

f4  4-byte  floating  (  -10‘,K  to  +  10l\  7  decimal  digit  precision) 

t'4  8-byte  lloating  (-10' K  to  +  10*\  17  decimal  digit  precision) 

One  numeric  formal  can  be  converted  to  or  substituted  for  any  other  numeric  format. 

9.  Type  Conversion. 

When  operating  on  two  numeric  domains  of  different  types,  iNGRt.s  converts  as  necessary  to 
make  the  types  identical. 

When  operating  on  an  integer  and  a  floating  point  number,  the  integer  is  converted  to  a  floating 
point  number  before  the  operation.  When  operating  on  two  integers  of  different  sizes,  the 
smaller  is  converted  to  the  si/c  of  the  larger.  When  operating  on  two  floating  point  number  of 
different  size,  the  larger  is  converted  to  the  smaller. 

The  following  table  summarizes  the  possible  combinations: 


ll 

i2 

i4 

f4 

f8 

il  - 

il 

i2 

i4 

F4 

f8 

i2  - 

i2 

i2 

i4 

f4 

f8 

i4  - 

i4 

i4 

i4 

f4 

f8 

f4  - 

t'4 

f4 

f4 

f4 

f4 

f8  - 

f8 

l'8 

re 

f4 

f8 

iNCikhS  provides  five  type  conversion  operators  specifically  for  overriding  the  default  actions. 
The  operators  are: 

intl(aexpr)  result  type  il 

int2(a_expr)  result  type  i2 

int4(a_expr)  result  type  i4 

float4(a_expr)  result  type  f4 

fioat8(a_expr)  result  type  f'8 

The  type  conversion  operators  convert  their  argument  ajsxpr  to  the  requested  type.  A  expr  can 
be  anything  including  character.  If  a  character  value  cannot  be  converted,  an  error  oecures  and 
processing  is  halted.  This  can  happen  only  if  the  syntax  of  the  character  value  is  incorrect. 

Overflow  is  not  checked  on  conversion. 

10.  Target  list 

A  target  list  is  a  parenthesized,  comma  separated  list  of  one  or  more  elements  ,  each  of  which 
musi  be  of  one  of  the  following  forms: 

a)  result  ait  name  is  a  expr 

Result  atfname  is  the  name  of  the  attribute  to  be  created  (or  an  already  existing  attribute  name 
in  the  case  of  update  statements.)  The  equal  sign  ("  =  ")  may  be  used  interchangeably  with  is. 
In  the  case  where  a  e\pr  is  anything  other  than  a  single  attribute,  this  form  must  be  used  to  as¬ 
sign  a  result  name  to  the  expression. 

b)  attribute 

In  the  case  of  a  remew,  the  resultant  domain  will  acquire  the  same  name  as  that  of  the  attribute 
being  retrieved.  In  the  case  of  update  statements  (append,  replan  ).  the  relation  being  updated 
must  have  a  domain  with  exactly  that  name. 

Inside  the  target  list  the  keyword  all  can  he  used  to  represent  all  domains.  1  or  example 

range  of  e  is  employee 

retrieve  (c  all)  where  e. salary  >  10000 
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will  retrieve  all  domains  of’ employee  for  those  tuples  which  satisfy  the  qualification.  All  can  be 
used  in  the  target  list  of  a  ret  new  ax  an  append.  The  domains  will  be  inserted  in  their  “create” 
order,  that  is,  the  same  order  they  were  listed  in  the  create  statement. 

1 1  Comparison  operators 

Comparison  operators  take  arbitrary  expressions  as  operands. 

<  (less  i ban) 

<®  (less  than  or  equal) 

>  (greater  than) 

>  =  (greater  than  or  equal) 

*  (equal  to) 

!  =  (not  equal  to) 

They  are  all  of  equal  precedence.  When  comparisons  are  made  on  character  attributes,  all 
blanks  are  ignored. 

12  Logical  operators 

Logical  operators  take  clauses  as  operands  and  group  !efi-to-right: 

not  (logical  not;  negation) 

and  (logical  and;  conjunction) 

or  (logical  or;  disjunction) 

Not  has  the  highest  precedence  of  the  three.  And  and  or  have  equal  precedence.  Parentheses 
may  be  used  for  arbitrary  grouping. 

13.  Qualification  (qual) 

A  qualification  consists  of  any  number  of  clauses  connected  by  logical  operators.  A  clause  is  a 
pair  of  expressions  connected  by  a  comparison  operator: 

a_expr  comparison  operator  a_expr 

Parentheses  may  be  used  for  arbitrary  grouping.  A  qualification  may  thus  be: 

clause 

not  qual 
qual  or  qual 
qual  and  qual 
(  qual ) 


14,  Functional  expressions 


A  Junctional  expression  consists  of  a  function  name  followed  by  a  parenthesized  (list  of) 
operand (s).  Functional  expressions  can  be  nested  to  any  level.  In  the  following  list  of  func¬ 
tions  supported  (n)  represents  an  arbitrary  numeric  type  expression.  The  format  of  the  result  is 
indicated  on  the  right. 


absOd  - 
ascii  in)  — 
aUn(/d  — 
conca Kci.M  - 
cos(/d  — 
exp(/d  — 
gamma  (/d  - 
log(/d  — 
mod  (n,b)  — 
sin </d  - 
sqrtOd  - 


same  as  n  (absolute  value) 

character  siring  (converts  numeric  to  character) 

18  (arctangent) 

character  (character  concatenation.  See  16.2) 

18  (cosine) 
f8  (exponential  of  n) 
f8  (log  gamma) 
f8  (natural  logarithm) 

same  as  bin  modulo  b.  n  and  b  must  be  i  I .  i2.  or  i4) 
1*8  (sine) 
f8  (square  root) 


15.  Aggregate  expressions 

Aggregate  expressions  provide  a  way  to  aggregate  a  computed  expression  over  a  set  of  tuples. 
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15  1.  Aggregation  operators 

The  definitions  of  the  aggregates  are  listed  below 


count  - 

(i4)  count  of  occurrences 

count  u  — 

(i4)  count  of  unique  occurrences 

sum  — 

summation 

sumu  — 

summation  of  unique  values 

avg  - 

<  18 )  average  (sum/count) 

avgu  - 

(18)  unique  average  (sumu/eountu) 

max  — 

maximum 

min  — 

minimum 

any  — 

(i2)  value  is  1  if  any  tuples  satisfy  the  qualification,  else  it  is  0 

15.2.  Simple  aggregate 

aggregation ^operator  [ajcxpr  [  where  qua!  1  ) 

A  simple  aggregate  evaluates  to  a  single  scalar  value.  Acxpr  is  aggregated  over  the  set  of  tu¬ 
ples  satisfying  the  qualification  (or  all  tuples  in  the  range  of  the  expression  if  no  qualification  is 
present).  Operators  sum  and  a vg  require  numeric  type  a  cxpr;  count,  any,  max  and  min  permit  a 
character  type  attribute  as  well  as  numeric  type  a  cxpr . 

Simple  aggregates  are  completely  local.  That  is,  they  are  logically  removed  from  the  query,  pro¬ 
cessed  separately,  and  replaced  by  their  scalar  value. 

15.3.  “any”  aggregate 

It  is  sometimes  useful  to  know  if  any  tuples  satisfy  a  particular  qualification.  One  way  of  doing 
this  is  by  using  the  aggregate  count  and  checking  whether  the  return  is  zero  or  non-zero.  Using 
any  instead  of  count  is  more  efficient  since  processing  is  stopped,  if  possible,  the  first  time  a  tu¬ 
ple  satisfies  a  qualification. 

Any  returns  1  if  the  qualification  is  true  and  0  otherwise. 

15.4.  Aggregate  functions 

aggregation  opera  tor  (acxpr  by  byjlomain 
I,  byjlomain}  [  where  qua!}  ) 

Aggregate  functions  are  extensions  of  simple  aggregates.  The  bv  operator  groups  (i.e.  parti¬ 
tions)  the  set  of  qualifying  tuples  by  bv  domain  values.  For  more  than  one  by  domain,  the 
values  which  are  grouped  by  are  the  concatenation  of  individual  by  domain  values.  A  expr  is  as 
in  simple  aggregates.  The  aggregate  function  evaluates  to  a  set  of  aggregate  results,  one  for 
each  partition  into  which  the  set  of  qualifying  tuples  has  been  grouped.  The  aggregate  value 
used  during  evaluation  of  the  query  is  the  value  associated  with  the  partition  into  which  the  tu¬ 
ple  currently  being  processed  would  fall. 

Unlike  simple  aggregates,  aggregate  functions  are  not  completely  local.  The  b\h\i,  which 
differentiates  aggregate  functions  from  simple  aggregates,  is  global  to  the  query.  Domains  in 
the  by  list  arc  automatically  linked  to  the  other  domains  in  the  query  which  arc  in  the  same  re¬ 
lation 

Example: 

/-  retrieve  the  average  salary  for  the  employees 
working  for  each  manager 
range  of  e  is  emplo>ee 

retrieve  (e. manager,  avosal  =  a>gU\sular>  b>  e. manager)) 

15  5  Aggregates  on  Unique  Values. 

It  is  occasionally  necessary  to  aggregate  on  unique  values  of  an  expression.  I  he  avgu.  \ tame 
and  ( ountu  aggregates  all  remove  duplicate  values  before  performing  the  aggregation,  lor  ex¬ 
ample: 
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count(c.  manager) 

would  tell  >ou  how  many  occurrences  of  c.manaxer  exist.  But 
countu(e.  manager) 

would  tell  you  how  many  unique  values  of  t\ manager  exist. 

16.  Special  character  operators 

There  are  three  special  features  which  are  particular  to  character  domains. 

16.1  Pattern  matching  characters 

There  are  four  characters  which  lake  on  special  meaning  when  used  in  character  constants 
(strings): 

*  matches  any  string  of  zero  or  more  characters. 

?  matches  any  single  character. 

[..]  matches  any  of  characters  in  the  brackets. 

These  characters  can  be  used  in  any  combination  to  form  a  variety  of  tests.  For  example 

where  e.name  =  -  matches  any  name. 

where  e.name  —  ME*"  -  matches  any  name  starting  with  ”EM. 

where  e.name  »  H*ein”  —  matches  all  names  ending  with  "einM 

where  e.name  =  "*laeioul*"  —  matches  any  name  with  at  least  one  vowel. 

where  e.name  =  "Allman?"  —  matches  any  seven  character  name  starting  with  "Allman". 

where  e.name  *»  MlA-J]*"  -  matches  any  name  starling  with  A,B,..,J. 

The  special  meaning  of  the  pattern  matching  characters  can  be  disabled  by  preceding  them  with 
a  "\’\  Thus  ’V"  refers  to  the  character  When  the  special  characters  appear  in  the  target  list 
they  must  be  escaped.  For  example: 

title  =  "\*\*\*  Ingres  \*\*\*" 

is  the  correct  way  to  assign  the  string  "***  ingres  ***"  to  the  domain  "title". 

16.2  Concatenation 

There  is  a  concatenation  operator  which  can  form  one  character  string  from  two.  Its  syntax  is 
"concat  (field  1,  field2)'\  The  size  of  the  new  character  string  is  the  sum  of  the  sizes  of  the  origi¬ 
nal  two.  Trailing  blanks  are  trimmed  from  the  first  field,  the  second  field  is  concatenated  and 
the  remainder  is  blank  padded.  The  result  is  never  trimmed  to  0  length,  however.  Concat  can 
be  arbitrarily  nested  inside  other  concats.  For  example. 

name  *  concat(concat(x.lastname,  V),  x.firstname) 
will  concatenate  x.lastname  with  a  comma  and  then  concatenate  x.firstname  to  that. 

16.3  Ascii  (numeric  to  character  translation) 

The  ascii  function  can  be  used  to  convert  a  numeric  field  to  its  character  representation.  This 
can  be  useful  when  it  is  desired  to  compare  a  numeric  value  with  a  character  value.  For  exam¬ 
ple. 

retrieve  (  ...  ) 

where  x.chardomain  *=  ascii(x.numdomain) 

Ascii  can  be  applied  to  a  character  value.  The  result  is  simply  the  character  value  unchanged. 
The  numeric  conversion  formats  are  determined  by  the  printing  formats  (see  ingres(unix) ). 

SFF  \I.SO 

append(quel),  delete(quel),  range(quel),  replace  (quel),  retrievc(quel),  ingres(unix) 


BU.s 

The  maximum  number  of  variables  which  can  appear  in  one  query  is  10. 
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Numeric  overflow,  underflow,  and  divide  by  ^ero  are  noi  delected. 
When  convening  between  numeric  types,  overflow  is  not  checked. 
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NAME 

range  —  declare  a  variable  to  range  over  a  relation 
SYNOPSIS 

range  of  variable  is  relname 
DESCRIPTION 

Range  is  used  to  declare  variables  which  will  be  used  in  subsequent  quel  statements.  The  van- 
able  is  associated  with  the  relation  specified  by  relname.  When  the  variable  is  used  in  subse¬ 
quent  statements  it  will  refer  to  a  tuple  in  the  named  relation.  A  range  declaration  remains  in 
effect  for  an  entire  INGRES  session  (until  exit  from  INGRES),  until  the  variable  is  redeclared  by  a 
subsequent  range  statement,  or  until  the  relation  is  removed  with  the  destroy  command. 

EXAMPLE 

/*  Declare  tuple  variable  e  to  range  over  relation  emp  *f 
range  of  e  is  emp 


SEE  ALSO 

quel(quel),  destroy(quel) 


BIGS 

Only  10  variable  declarations  may  be  in  effect  at  any  time.  After  the  10th  range  statement,  the 
least  recently  referenced  variable  is  re —  used  for  the  next  range  statement. 
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\  wit 

replace  -  replace  \  allies  of  domains  in  a  relation 
M  NOHSIS 

replace  tuplevariable  I  target  list)  (where  quail 
DESl  RIPTION 

Replace  changes  the  values  of  the  domains  specified  in  the  target. Jim  for  all  tuples  which  satisfy 
the  qualification  qua!.  The  tuple  variable  must  have  been  declared  to  range  over  the  relation 
which  is  to  be  modified.  Note  that  a  tuple  variable  is  required  and  not  the  relation  name.  Only 
domains  which  are  to  be  modified  need  appear  in  the  target Jtsi.  These  domains  must  be 
specified  as  resultattnames  in  the  target  Jist  either  explicitly  or  by  default  (see  quel(quel)). 

Numeric  domains  may  be  replaced  by  values  of  any  numeric  type  (with  the  exception  noted 
below).  Replacement  values  will  be  converted  to  the  type  of  the  result  domain. 

Onl\  the  owner  of  a  relation,  or  a  user  with  replace  pemission  on  the  relation  can  do  replace. 

If  the  tuple  update  would  violate  an  integrity  constraint  (see  integrity  (quel )  > ,  it  is  not  done. 

EXAMPLE 

/*  Give  all  employees  who  work  for  Smith  a  10%  raise  */ 
range  of  e  is  emp 

replace  e(sal  =  1.1  *  e.sal)  where  e.mgr  —  ’’Smith" 

SEE  ALSO 

integrity  (quel )  ^  permii(quel),  quel(quel),  range(quel) 

DIAGNOSTIC'S 

Use  of  a  numeric  type  expression  to  replace  a  character  type  domain  or  vice  versa  will  produce 
diagnostics. 

Bl  (.S 
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NAME 

retrieve  —  remove  tuples  from  a  relation 
NOPSIS 

retrieve  llinto]  relnarne]  (target  list)  (where  qual) 
retrieve  unique  (target  list)  (where  qual) 

DESt  R1PTION 

Retrieve  will  gel  all  tuples  which  satisfy  the  qualification  and  either  display  them  on  the  terminal 
(standard  output)  or  store  them  in  a  new'  relation. 

If  a  relname  is  specified,  the  result  of  the  query  will  be  stored  in  a  new  relation  with  the  indi¬ 
cated  name.  A  relation  with  this  name  owned  by  the  user  must  not  already  exist.  The  current 
user  will  be  the  owner  of  the  new  relation  The  relation  will  have  domain  names  as  specified  in 
the  target Jist  resultuttnames.  The  new  relation  will  be  saved  on  the  system  for  seven  (7)  days 
unless  explicitly  saved  by  the  user  until  a  later  dale. 

If  the  keyword  unique  is  present,  tuples  will  be  sorted  on  the  first  domain,  and  duplicates  will 
be  removed,  before  being  displayed. 

The  keyword  all  can  be  used  when  it  is  desired  to  retrieve  all  domains. 

If  no  result  relname  is  specified  then  the  result  of  the  query  will  be  displayed  on  the  terminal 
and  will  not  be  saved.  Duplicate  tuples  are  not  removed  when  the  result  is  displayed  on  the 
terminal. 

The  formal  in  which  domains  arc  primed  can  be  defined  at  the  lime  ingres  is  invoked  (see 
ingres(unix) ). 

If  a  result  relation  is  specified  then  the  default  procedure  is  to  modify  the  result  relation  to  an 
cheapsort  storage  structure  removing  duplicate  tuples  in  the  process. 

If  the  default  cheapsort  structure  is  not  desired,  the  user  can  override  this  at  the  time  Ingres  is 
invoked  by  using  the  -r  switch  (see  ingres(unix)). 

Only  the  relation's  owner  and  users  with  retrieve  permission  may  retrieve  from  it. 

l  \  \MPLE 

/*  Find  all  employees  who  make  more  than  their  manager  */ 
range  of  e  is  emp 
range  of  m  is  emp 

retrieve  (e.name)  where  e.mgr  —  m.name 
and  e.sal  >  m.sal 

/*  Retrieve  all  domains  for  those  who  make  more 
than  the  average  salary  */ 
retrieve  into  temp  (c.all)  where  e.sal  >  avg(e.sal) 
h  retrieve  employees's  names  sorted  */ 
retrieve  unique  (e.name) 


sEE  W.SO 

modify  (quel) ,  permit  (quel),  qucMquel),  rangc(quel),  savclquel),  ingres(unix) 

!>l  \0\<)Sl  II  S 
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\  WH 

save  -  save  a  relation  until  dale. 

NORMS 

save  rel name  until  month  day  year 
Of  Si  RUM  ION 

Saw  in  used  to  keep  relations  beyond  ihe  default  7  day  life  span, 

Wonih  can  be  an  integer  from  1  through  12,  or  the  name  of  the  month,  either  abbreviated  or 
spelled  out 

Only  the  owner  of  a  relation  can  saw  that  relation.  There  is  an  iNCiHl.s  process  which  typically 
removes  a  relation  immediately  after  its  expiration  date  has  passed. 

The  actual  program  which  destroys  relations  is  called  purge.  It  is  not  automatically  run.  It  is  a 
local  decision  when  expired  relations  are  removed. 

System  relations  have  no  expiration  date. 

K\  WIPt.E 

/*  Save  the  emp  relation  until  the  end  of  February  1987  V 
save  emp  until  feb  28  1987 

SKF  VI  SO 

create(quel),  retrieve(quel),  purge(unix) 
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N  \\|f 

view  -  define  a  virtual  relation 
XOPSIS 

define  view  name  (target-list)  [  where  qual  ) 

DESCRIPTION 

The  syntax  of  the  view  statement  is  almost  identical  to  the  retrieve  into  stutmeni.  however,  the 
data  is  not  retrieved.  Instead,  the  definition  is  stored.  When  the  relation  name  is  later  used, 
the  query  is  converted  to  operate  on  the  relations  specified  in  the  target-list. 

All  forms  of  retrieval  on  the  view  are  fully  supported,  but  only  a  limited  set  of  updates  are  sup¬ 
ported  because  of  anomolies  which  can  appear.  Almost  no  updates  are  supported  on  views 
which  span  more  than  one  relation.  No  updates  are  supported  that  affect  a  domain  in  the 
qualification  of  the  view  or  that  affect  a  domain  which  does  not  translate  into  a  simple  attribute. 

In  general,  updates  are  supported  if  and  only  if  it  can  be  guaranteed  (without  looking  at  the  ac¬ 
tual  data)  that  the  result  of  updating  the  view  is  identical  to  that  of  updating  the  corresponding 
real  relation. 

The  person  who  defines  a  view  must  own  all  relations  upon  which  the  view  is  based. 

EXAMPLE 

range  of  e  is  employee 
range  of  d  is  dept 

define  view  empdpt  (ename  =  e.name,  e.sal,  dname  =  d.name) 
where  e.mgr  *=  d.mgr 

>EE  ALSO 

retrieve(quel),  destroy(quel) 
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\  \ME 

copydb  -  create  batch  files  to  copy  out  a  data  base  and  restore  it. 
nopsis 

copydb  (  — u name]  database  fuil-path-name-of-directory  i  relation  ...  ) 

DESCRIPTION 

Copydb  creates  two  INGRES  command  files  in  the  directory:  Copy. out,  which  contains  Quel  in- 
stuctions  which  will  copy  all  relations  owned  by  the  user  into  files  in  the  named  directory,  and 
copy. in*  which  contains  instructions  to  copy  the  files  into  relations,  create  indexes  and  do 
modifies.  The  files  will  have  the  same  names  as  the  relations  with  the  users  INGRES  id  tacked 
on  the  end.  (The  directory  MUST  NOT  be  the  same  as  the  data  base  directory  as  the  files  have 
the  same  names  as  the  relation  files.)  The  —  u  flag  may  be  used  to  run  copydb  with  a  different 
user  id.  (The  fact  that  copydb  creates  the  copy  files  does  not  imply  that  the  user  can  necessarily 
access  the  specified  relation).  If  relation  names  are  specified  only  those  relations  will  be  includ¬ 
ed  in  the  copy  files. 

Copydb  is  written  in  Equel  and  will  access  the  database  in  the  usual  manner.  It  does  not  have 
to  run  as  the  INGRES  user. 


EXAMPLE 

chdir  /mnt/mydir 

copydb  db  /mnt/mydir/backup 

mgres  db  <  back  up/copy,  out 

tp  rl  backup 

rm  —  r  backup 

tp  xl 

ingres  db  <  backup/copy. in 
DIAGNOSTICS 

Copydb  will  give  self-explanatory  diagnostics.  If  “too  many  indexes"  is  reported  it  means  that 
more  than  ten  indexes  have  been  specified  on  one  relation.  The  constant  can  be  increased  and 
the  program  recompiled.  Other  limits  are  set  to  the  system  limits. 


BIGS 

Copydb  assumes  that  indexes  which  are  ISAM  do  not  need  to  be  remodified.  Copydb  cannot  tell 
if  the  relation  was  modified  with  a  fillfactor  or  minpages  specification.  The  copy  .in  file  may  be 
edited  to  reflect  this. 


-  I  - 
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NAME 

creatdb  —  create  a  data  base 
SYNOPSIS 

creatdb  I  —  u name  1  [  — e  ]  l  —  m  ]  [  ±c  1  l  ±q  }  dbname 
DESCRIPTION 

Creatdb  creates  a  new  INGRES  database,  or  modifies  the  status  of  an  existing  database.  The  per¬ 
son  who  executes  this  command  becomes  the  Database  Administrator  (DBA)  for  the  database. 
The  DBA  has  special  powers  not  granted  to  ordinary  users. 

Dbname  is  the  name  of  the  database  to  be  created.  The  name  must  be  unique  among  all 
INGRES  users. 

The  flags  ±c  and  ±q  specify  options  on  the  database.  The  form  -Ex  turns  an  option  on,  while 
—  x  turns  an  option  off.  The  — c  flag  turns  off  the  concurrency  control  scheme  (default  on). 
The  +q  flag  turns  on  query  modification  (default  off). 

Concurrency  control  should  not  be  turned  off  except  on  databases  which  are  never  accessed  by 
more  than  one  user.  This  applies  even  if  users  do  not  share  data  relations,  since  system  rela¬ 
tions  are  still  shared.  If  the  concurrency  control  scheme  is  not  installed  in  UNIX,  or  if  the  spe¬ 
cial  file  /dev/lock  does  not  exist  or  is  not  accessible  for  read-write  by  INGRES,  concurrency  con¬ 
trol  acts  as  though  it  is  off  (although  it  will  suddenly  come  on  when  the  lock  driver  is  installed 
in  UNIX). 

Query  modification  must  be  turned  on  for  the  protection,  integrity,  and  view  subsystems  to 
work,  however,  the  system  will  run  slightly  slower  in  some  cases  if  it  is  turned  on.  It  is  possi¬ 
ble  to  turn  query  modification  on  if  it  is  already  off  in  an  existing  database,  but  it  is  not  possible 
to  turn  it  off  if  it  is  already  on. 

Databases  with  query  modification  turned  off  create  new  relations  with  all  access  permitted  for 
all  users,  instead  of  no  access  except  to  the  owner,  the  default  for  databases  with  query 
modification  enabled. 

Database  options  for  an  existing  database  may  be  modified  by  stating  the  —  e  flag.  The  database 
is  adjusted  to  conform  to  the  option  flags.  For  example: 
creatdb  —  e  +  q  mydb 

turns  query  modification  on  for  database  “mydb”  (but  leaves  concurrency  control  alone).  Only 
the  database  administrator  (DBA)  may  use  the  —  e  flag. 

When  query  modification  is  turned  on,  new  relations  will  be  created  with  no  access,  but  previ¬ 
ously  created  relations  will  still  have  all  access  to  everyone.  The  destroy  command  may  be  used 
to  remove  this  global  permission,  after  which  more  selective  permissions  may  be  specified  with 
the  permit  command. 

The  INGRES  user  may  use  the  ~u  flag  to  specify  a  differem  DBA:  the  flag  should  be  immediate¬ 
ly  followed  by  the  login  name  of  the  user  who  should  be  the  DBA. 

The  — m  flag  specifies  that  the  UNIX  directory  in  which  the  database  is  lo  reside  already  exists. 
This  should  only  be  needed  if  the  directory  if  a  mounted  file  system,  as  might  occur  for  a  very 
large  database.  The  directory  must  exist  (as  .../data/base/d/vwwe),  must  be  mode  777,  and 
must  be  empty  of  all  files. 

The  user  who  executes  this  command  must  have  the  U_CREATDB  bit  set  in  the  status  field  of 
her  entry  in  the  users  file. 

The  Ingres  superuser  can  create  a  file  in  .../data/base  containing  a  single  line  which  is  the  full 
pathname  of  the  location  of  the  database.  The  file  must  be  owned  by  INGRES  and  be  mode  644. 
When  the  database  is  created,  it  will  be  created  in  the  file  named,  rather  than  in  the  directory 
.../data/base.  For  example,  if  the  file  .../data/base/ericdb  contained  the  line 
/mnt/eric/database 

then  the  database  called  “ericdb”  would  be  physically  stored  in  the  directory 
/mnt/eric/database  rather  than  in  the  directory  .../data/base/ericdb. 
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EXAMPLE 

crealdb  demo 

creatdb  —  ueric  —  q  eries  db 
creatdb  —  e  +q  — c  —  u:av  erics  db 


FILES 

../files/dbtmplt6.2 
..  /files/data/base/* 

.../files/datadir/*  (for  compatibility  with  previous  versions) 

SEE  ALSO 

demodb(unix),  destroydb(unix),  users(files),  chmod(l),  destroydb(quel),  permit(quel) 
DIAGNOSTICS 

No  database  name  specified. 

You  have  not  specified  the  name  of  the  database  to  create  (or  modify)  with  the  com¬ 
mand. 

You  may  not  access  this  database 

Your  entry  in  the  users  file  says  you  are  not  authorized  to  access  this  database. 

You  are  not  a  valid  INGRES  user 

You  do  not  have  a  users  file  entry,  and  can  not  do  anything  with  INGRES  at  all. 

You  are  not  allowed  this  command 

The  UCREATDB  bit  is  not  set  in  your  users  file  entry. 

You  may  not  use  the  —  u  flag 

Only  the  INGRES  superuser  may  become  someone  else. 

<name>  does  not  exist 

With  — e  or  —  m,  the  directory  does  not  exist. 

<name>  already  exists 

Without  either  — e  or  —  m,  the  database  (actually,  the  directory)  already  exists. 
<name>  is  not  empty 

With  the  — m  flag,  the  directory  you  named  must  be  empty. 

You  are  not  the  DBA  for  this  database 

With  the  — e  flag,  you  must  be  the  database  administrator. 
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NAME 

destroydb  —  destroy  an  existing  database 
S^  NOPS1S 

destroydb  (  — s  ]  (  — m  1  dbname 
DESCRIPTION 

Destroydb  will  remove  all  reference  to  an  existing  database.  The  directory  of  the  database  and 
all  files  in  that  directory  will  be  removed. 

To  execute  this  command  the  current  user  must  be  the  database  administrator  for  the  database 
in  question,  or  must  be  the  INGRES  superuser  and  have  the  — s  flag  stated. 

The  — m  flag  causes  destroydb  not  to  remove  the  UNIX  directory.  This  is  useful  when  the  direc¬ 
tory  is  a  separate  mounted  Unix  file  system. 

EXAMPLE 

destroydb  demo 
destroydb  —  $  erics  db 


EllES 

../data/base/* 

.. Vdatadir/*  (for  compatibility  with  previous  versions) 

SEE  ALSO 

creatdb(unix) 

DIAGNOSTICS 

invalid  dbname  —  the  database  name  specified  is  not  a  valid  name. 

you  may  not  reference  this  database  —  the  database  may  exist,  but  you  do  not  have  permission 
to  do  anything  with  it. 

you  may  not  use  the  — s  flag  —  you  have  tried  to  use  the  ~s  flag,  but  you  are  not  the  INGRES 
superuser. 

you  are  not  the  dba  —  someone  else  created  this  database, 
database  does  not  exist  —  this  database  does  not  exist. 
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WMF 

equel  —  Embedded  QIJEL  interface  to  C 
s>  noEsis 

equel  [  — d  1  [  — f  ]  l  — r  1  file.q  ... 

DESCRIPTION 

Equel  provides  ihe  user  with  a  method  of  interfacing  the  general  purpose  programming  language 
“C"  with  Ingres.  It  consists  of  the  equel  pre-compiler  and  the  equel  runtime  library. 

Compilation 

The  precompiler  is  invoked  with  the  statement: 

equel  [< flags >)  filel.q  (< flags >]  file2.q  ... 

where  filel.q  are  the  source  input  file  names,  which  must  end  with  .q.  The  output  is  written  to 
the  file  “filen.c".  As  many  files  as  wished  may  be  specified. 

The  flags  that  may  be  used  are: 

— d  Generate  code  to  print  source  listing  file  name  and  line  number  when  a  run-time  error  oc¬ 
curs.  This  can  be  useful  for  debugging,  but  takes  up  process  space.  Defaults  to  off. 

—  f  Forces  code  to  be  on  the  same  line  in  the  output  file  as  it  is  in  the  input  file  to  ease  inter¬ 

preting  C  diagnostic  messages.  EQUEL  will  usually  try  to  get  all  C  code  lines  in  the  output 
file  on  the  same  lines  as  they  were  in  the  input  file.  Sometimes  it  must  break  up  queries 
into  several  lines  to  avoid  C-preprocessor  line  overflows,  possibly  moving  some  C  code 
ahead  some  lines.  With  the  — f  flag  specified  this  will  never  happen  and,  though  the  line 
buffer  may  overflow,  C  lines  will  be  on  the  right  line.  This  is  useful  for  finding  the  line  in 
the  source  file  that  C  error  diagnostics  on  the  output  file  refer  to. 

—  r  Resets  flags  to  default  values.  Used  to  supress  other  flags  for  some  of  the  files  in  the  ar¬ 

gument  list. 

The  output  files  may  than  be  compiled  using  the  C  compiler: 
cc  filel.c  file2.c  ...  —  lq 

The  —  lq  requests  the  use  of  the  equel  object  library. 

All  EQUEL  routines  and  globals  begin  with  the  characters  "11",  and  so  all  globals  variables  and 
procedure  names  of  the  form  llxv.v  are  reserved  for  use  by  EQUEL  and  should  be  avoided  by 
equel  users. 

Basic  Syntax 

EQUE1  commands  are  indicated  by  lines  which  begin  with  a  double  pound  sign  (“##").  Other 
lines  are  simply  copied  as  is.  All  normal  INGRES  commands  may  be  used  in  tQt  1 1  and  have  the 
same  effect  as  if  invoked  through  the  interactive  terminal  monitor.  Only  retrieve  commands 
with  no  result  relation  specified  have  a  different  syntax  and  meaning. 

The  format  of  retrieve  without  a  result  relation  is  modified  to: 

##  retrieve  (C-variable  *  afen  1  ,  C-variable  =  afen  )  ) 
optionall)  followed  (immediately)  bv: 

##  1  w  here  qua!  1 

##  ( 

/*  C  code  */ 

##  ) 

I  Ins  statement  causes  the  “C-code"  to  be  executed  once  for  each  tuple  retrieved,  with  the 
’*(  -variable  's  set  appropriately.  Numeric  values  of  any  type  arc  converted  as  necessary  No 
conversion  is  done  between  numeric  and  character  values.  (The  normal  ingkis  asm  function 
may  be  used  for  this  purpose.) 


-  1  - 


EQUEL  i  UNIX ) 


3/14/79 


EQUEL  (UNIX  ) 


Also,  the  following  equel  commands  are  permitted. 

##  ingres  [ingres  flags]  databasename 

This  command  starts  Ingres  running,  and  directs  all  dynamically  following  queries 
to  the  database  data  base  name.  It  is  a  run-time  error  to  execute  this  command 
twice  without  an  intervening  "##  exit",  as  well  as  to  issue  queries  while  an  "## 
ingres"  statement  is  not  in  effect.  Each  flag  should  be  enclosed  in  quotes  to  avoid 
confusion  in  the  EQUEL  parser: 

##  ingres  M  —  f4fl0.2"  M  —  i212"  demo 

##  exit 

Exit  simply  exits  from  INGRES.  It  is  equivalent  to  the  \q  command  to  the  teletype 
monitor. 

Parametrized  Quel  Statements 

Quel  statements  with  target  lists  may  be  "parametrized".  This  is  indicated  by  preceding  the 
statement  with  the  keyword  "param".  The  target  list  of  a  parametrized  statement  has  the  form 

(  //_  var,  argv  ) 

where  tfvar  is  taken  to  be  a  string  pointer  at  execution  time  (it  may  be  a  string  constant)  and 
interpreted  as  follows.  For  any  parametrized  equel  statement  except  a  retrieve  without  a  result 
relation  (no  "into  rel")  (i.e.  append,  copy,  create,  replace,  retrieve  into)  the  string  tlvar  is  tak¬ 
en  to  be  a  regular  target  list  except  that  wherever  a  '%'  appears  a  valid  Ingres  type  (f4,  f8,  i2, 
i4,  c)  is  expected  to  follow.  Each  of  these  is  replaced  by  the  value  of  the  corresponding  entry 
into  argv  (starting  at  0)  which  is  interpreted  to  be  a  pointer  to  a  variable  of  the  type  indicated 
by  the  4%*  sequence.  Neither  argv  nor  the  variables  which  it  points  to  need  be  declared  to  EQL 
EL.  For  example: 

char  ♦argvtlOl; 

argv[0]  —  &double_var; 
argvf  1  ]  =  &int_var; 

##  param  append  to  rel 

##  ("doml  =  %f8,  dom2  —  %i2”,  argv) 

##  /*  to  escape  the  M%<ingres_type>"  mechanism  use  "%%"  */ 

##  /♦  This  places  a  single  k%'  in  the  string.  */ 

On  a  retrieve  to  C-variables,  within  il^var,  instead  of  the  C-variable  to  retrieve  into,  the  same 
escape  sequences  are  used  to  denote  the  type  of  the  corresponding  argv  entry  into  which 
the  value  will  be  retrieved. 

The  qualification  of  any  query  may  be  replaced  by  a  siring  valued  variable,  whose  contents  is 
interpreted  at  run  lime  as  the  text  of  the  qualification. 

The  copy  statement  may  also  be  parametrized.  The  form  of  the  parametrized  copy  is  analogous 
to  the  other  parametrized  statements:  the  target  list  may  be  parametrized  in  the  same  manner  as 
the  append  statements,  and  furthermore,  the  from/into  keyword  may  be  replaced  by  a  string 
valued  variable  whose  content  at  run  time  should  be  into  or  from. 

Declarations 

Any  valid  C  variable  declaration  on  a  line  beginning  with  a  "##"  declares  a  C-variable  that 
mat  be  used  in  an  EQl'El  statement  and  us  a  normal  variable.  All  variables  must  be  declared 
'before  being  used. ..  Any  where  a  constant  may  appear  in  an  ingrin  command,  a  C -variable  may 
appear.  The  value  of  the  C-variable  is  substituted  at  execution  time 

Neither  nested  structures  nor  variables  of  type  char  (as  opposed  to  pointer  to  char  or  array  of 
char)  are  allowed.  Furthermore,  there  are  two  restrictions  in  the  way  variables  arc  referenced 
within  eqijel  statements.  All  variable  usages  must  be  dereferenced  and/or  subscripted  (for  ar¬ 
rays  and  pointers),  or  selected  (for  structure  variables)  to  yield  lvalues  (scalar  values).  Chat 
variables  are  used  by  EQUEL  as  a  means  to  use  strings.  Therefore  when  using  a  char  array  or 
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pointer  it  must  be  dereferenced  only  to  a  "char  Also,  variables  may  not  have  parentheses 
m  their  references.  For  example: 

##  struct  xxx 

##  { 

ini  i; 

##  int  *ip; 

##  ]  ♦*struet_var; 

/*  not  allowed  */ 

##  delete  p  where  p.ifield  =  *(*struct_var)->ip 
/♦  allowed  ♦/ 

##  delete  p  where  p.ifield  *=  *struct_var[0]->  ip 

C  variables  declared  to  KQUtL  have  either  global  or  local  scope.  Their  scope  is  local  if  their  de¬ 
claration  is  within  a  free  (not  bound  to  a  retrieve)  block  declared  to  i-otTF.L.  For  example: 

/♦  globals  scope  variable  ♦/ 

##  int  Gint; 

func(i) 
int  i; 

##  { 

/*  local  scope  variable  ♦/ 

##  int  *gintp; 

##} 

If  a  variable  of  one  of  the  char  types  is  used  almost  anywhere  in  an  fcQUHL  statement  the  con¬ 
tent  of  that  variable  is  used  at  run  time.  For  example: 

##  char  ♦dbnamelMAXDATABASES  +  H; 

int  currentdb; 

dbnamelcurrentdb)  ~  "demo"; 

##  ingres  dbname  [current  db] 

will  cause  iNGKt  s  to  be  invoked  with  data  base  "demo".  However,  if  a  variable's  name  is  to  be 
used  as  a  constant,  then  the  non-referencing  operator  k#'  should  be  used.  For  example: 

##  char  ♦demo; 

demo  —  "my  database": 

/♦  ingres  —  d  my  database  */ 

##  ingres  d"  demo 

N 

/*  ingres  — d  demo  ♦/ 

##  ingres  d"  #demo 

T  he  C  -preprocessor's  #indude  feature  may  be  used  on  files  containing  equel  statements  and 
declarations  if  these  files  are  named  anyihtHK*n*h.  An  igtn  processed  version  of  the  tile, 
which  will  be  #im.T tided  by  the  C-preproccssor,  is  left  in  anythui^xAu 

Errors  and  Interrupts 

iViKi  s  and  run-time  t  qi  }  i  errors  cause  the  routine  llerror  to  be  called,  with  the  error  inimhci 
and  the  parameters  to  the  error  in  an  array  of  string  pointers  as  in  a  C  language  main  routine 
1  he  error  message  will  be  looked  up  and  printed,  before  printing  the  error  message,  the  routine 
t*llprint  errH)  is  called  vnih  the  error  number  that  ocurred  as  its  single  argument  The  ermr 
message  corresponding  to  the  error  number  returned  by  Mlprini  errHl  will  be  printed  Print¬ 
ing  will  be  supressed  if  Mlprini  err)()  returns  0  llprmt  err  mas  be  reassigned  to.  and  is  use 
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ful  for  programs  which  map  INGRES  errors  into  their  own  error  messages.  In  addition,  if  the 
d"  Hag  was  set  the  file  name  and  line  number  of  the  error  will  be  printed.  The  user  mat 
write  an  Ilerror  routine  to  do  other  tasks  as  long  as  the  setting  of  Ilerrflag  is  not  modified  as 
this  is  used  to  exit  retrieves  correctly. 

Interrupts  are  caught  by  equel  if  they  are  not  being  ignored.  This  insures  that  the  rest  of 
INGRES  is  in  sync  with  the  equel  process.  There  is  a  function  pointer,  Ilinterrupt,  which  points 
to  a  function  to  call  after  the  interrupt  is  caught.  The  user  may  use  this  to  service  the  interrupt 
It  is  initialized  to  HexitOM  and  is  called  with  -1  as  its  argument.  For  example: 

extern  int  (^Ilinterrupt) (); 
extern  resetO; 

setexitO; 

Ilinterrupt  =  reset; 
mainloopO; 

To  ignore  interrupts,  signal!)  should  be  called  before  the  ##  ingres  satatemenl  is  executed. 


FILES 

.../files/error6.2  * 

Can  be  used  by  the  user  to  decipher  Ingres  error  numbers. 

/lib/libq.a 

Run  time  library. 

SEE  ALSO 

.../doc/other/equeltut.q,  C  reference  manual,  ingres(UNIX),  quel(QUEL) 

BIGS 

The  C-code  embedded  in  the  tuple-by-tuple  retrieve  operation  may  not  contain  additional 
QUEL  statements  or  recursive  invocations  of  Ingres. 

There  is  no  way  to  specify  an  il  format  C-variable. 

Includes  of  an  equel  file  within  a  parameterized  target  list,  or  within  a  C  variable's  array  sub¬ 
scription  brackets,  isn’t  done  correctly. 
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name 

helpr  -  get  information  about  a  database. 
s\\oPsis 

helpr  [  —uname]  l  ±w  ]  database  relation  ... 

DESCRIPTION 

Helpr  gives  information  about  the  named  relation (s)  out  of  the  database  specified,  exactly  like 
the  help  command. 

Flags  accepted  are  —  u  and  ±u.  Their  meanings  are  identical  to  the  meanings  of  the  same  flags 
in  INGRES. 

SEE  ALSO 

ingres(unix),  help(quel) 

DIAGNOSTICS 

bad  flag  —  you  have  specified  a  flag  which  is  not  legal  or  is  in  bad  format, 
you  may  not  access  database  —  this  database  is  prohibited  to  you  based  on  status  information  in 
the  users  file. 

cannot  access  database  —  the  database  does  not  exist. 
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NAME 

ingres  -  INGRES  relational  data  base  management  system 
SYNOPSIS 

ingres  [  flags  ]  dbname  l  processtable  ] 

DESCRIPTION 

This  is  the  UNIX  command  which  is  used  to  invoke  INGRES.  Dbname  is  the  name  of  an  existing 
data  base.  The  optional  flags  have  the  following  meanings  (a  means  the  flag  may  be  stal¬ 

ed  "  +  a"  to  set  option  v  or  "-v"  to  clear  option  a.  ifc  —  "  alone  means  that  “  —  a"  must  be 
stated  to  get  the  a  function): 

±U  Enable/disable  direct  update  of  the  system  relations  and  secondary  i ndicies  You 

must  have  the  000004  bit  in  the  status  field  of  the  users  file  set  for  this  flag  to  be  ac¬ 
cepted.  This  option  is  provided  for  system  debugging  and  is  strongly  discouraged  for 
normal  use. 

—  u name  Pretend  you  are  the  user  with  login  name  name  (found  in  the  users  file).  If  name  is 

of  the  form  :aa\  ay  is  the  two  character  user  code  of  a  user.  This  may  only  be  used 
by  the  DBA  for  the  database  or  by  the  INGRES  superuser. 

—  c/V  Set  the  minimum  field  width  for  printing  character  domains  to  N.  The  default  is  6. 

—  ilN  Set  integer  output  field  width  to  N.  I  may  be  1,  2,  or  4  for  il's,  i2's,  or  i4's  repec- 

lively. 

—  iixM.N  Set  floating  point  output  field  width  to  M  characters  with  A' decimal  places,  /may  be 

4  or  8  to  apply  to  f4's  or  f8's  respectively,  .v  may  be  e,  E,  f,  F,  g,  G,  n,  or  N  to 
specify  an  output  format.  E  is  exponential  form,  F  is  floating  point  form,  and  G  and 
N  are  identical  to  F  unless  the  number  is  too  big  to  fit  in  that  field,  when  it  is  output 
in  E  format.  G  format  guarantees  decimal  point  alignment;  N  does  not.  The  de¬ 
fault  format  for  both  is  nl0.3. 

—  vA  Set  the  column  seperator  for  retrieves  to  the  terminal  and  print  commands  to  be  A'. 

The  default  is  vertical  bar. 

—  r M  Set  modify  mode  on  the  retrieve  command  to  M.  M  may  be  isam,  cisam,  hash, 

chash,  heap,  cheap,  heapsort,  or  cheapsort,  for  ISAM,  compressed  ISAM,  hash 
table,  compressed  hash  table,  heap,  compressed  heap,  sorted  heap,  or  compressed 
sorted  heap.  The  default  is  ‘"cheapsort". 

—  ii A/  Set  modify  mode  on  the  index  command  to  M.  M  can  take  the  same  values  as  the 

—  r  Hag  above.  Default  is  "isam". 

±a  Set/clear  the  autoclear  option  in  the  terminal  monitor.  It  defaults  to  set. 

±b  Sct/resct  batch  update.  Users  must  the  000002  bit  set  in  the  status  field  of  the  users 

file  to  clear  this  Hag.  This  flag  is  normally  set.  When  clear,  queries  will  run  slightly 
faster,  but  no  recovery  can  take  place.  Queries  which  update  a  secondary  index  au¬ 
tomatically  set  this  Hag  for  that  query  only. 

±d  Print/don't  print  the  dayfile.  Normally  set. 

± s  Print/don't  print  any  of  the  monitor  messages,  including  prompts.  This  flags  is  nor¬ 

mally  set.  If  cleared,  it  also  clears  the  — d  flag. 

±w  Wail/don't  wait  for  the  database.  If  the  +w  Hag  is  present,  Ingres  will  wait  if  cer¬ 

tain  processes  are  running  (purge, restore,  and/or  sysmod)  on  the  given  data  base. 
Upon  completion  of  those  processes  INGRES  will  proceed  If  the  — w  Hag  is  present, 
a  message  is  returned  and  execution  stopped  if  the  data  base  is  not  available.  If  the 
flag  is  omitted  and  the  data  base  is  unavailable,  the  error  message  is  returned  if 
Ingres  is  running  in  foreground  (more  precisly  if  the  standard  input  is  from  a  ter¬ 
minal),  otherwise  the  wail  option  is  invoked. 

Process  table  is  the  pathname  of  a  UNIX  file  which  may  be  used  to  specify  the  run-time 
configuration  of  Ingres.  This  feature  is  intended  for  use  in  system  maintenance  only,  and  its 
unenlightened  use  by  the  user  community  is  strongly  discouraged 

Note  It  is  possible  to  run  the  monitor  as  a  batch-processing  interface  using  the  ‘<  \  ">'  and  T 
operators  of  the  t  M\  shell,  provided  the  input  file  is  in  proper  monitor-format. 
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FWMPl.f 

Ingres  demo 

mgres  -d  demo 

mgres  —  s  demo  <  batchfile 

mgres  —  F4g  12.2  —  i  1 3  +b  — rhash  demo 


FILES 

../files/users  —  valid  INGRES  users 

.../data/base/*  —  data  bases 

.../datadir/*  —  for  compatability  with  previous  versions 

.../files/proctab6.2  -  runtime  configuration  file 

SEE  ALSO 

monitor(quel) 

DIAGNOSTICS 

Too  many  options  to  INGRES  —  you  have  stated  too  many  flags  as  INGRES  options. 

Bad  flag  formal  —  you  have  slated  a  flag  in  a  format  which  is  not  intelligible,  or  a  bad  flag  en¬ 
tirely. 

Too  many  parameters  —  you  have  given  a  database  name,  a  process  table  name,  and  “some¬ 
thing  else”  which  Ingres  doesn't  know  what  to  do  with. 

No  database  name  specified 

Improper  database  name  —  the  database  name  is  not  legal. 

You  may  not  access  database  name  —  according  to  the  users  file,  you  do  not  have  permission  to 
enter  this  database. 

You  are  not  authorized  to  use  the  flag  flag  —  the  flag  specified  requires  some  special  authoriza¬ 
tion,  such  as  a  bit  in  the  users  file,  which  you  do  not  have. 

Database  name  does  not  exist 

You  are  not  a  valid  INGRES  user  —  you  have  not  been  entered  into  the  users  file,  which  means 
that  you  may  not  use  INGRES  at  all. 

You  may  not  specify  this  process  table  —  special  authorization  is  needed  to  specify  process 
tables. 

Database  temporarily  unavailable  -  someone  else  is  currently  performing  some  operation  on 
the  database  which  makes  it  impossible  for  you  to  even  log  in.  This  condition  should 
disappear  shortly. 
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NAME 

geoquel  —  GEO-QUEL  data  display  system 
SYNOPSIS 

geoquel  [  — s  ]  [  — d  ]  l  — a  ]  [  — 1 7“ I  [  —tn7]  dbname 
DESCRIPTION 

geo-quel  is  a  geographical  interface  to  INGRES. 

Dbname  is  ihe  name  of  an  existing  data  base. 

The  format  of  the  graphic  output  depends  upon  the  type  of  terminal  in  use.  geo-quel  will  look 
up  the  terminal  type  at  login  time  and  produce  output  appropriate  for  that  terminal.  If  the  ter¬ 
minal  in  use  is  incapable  of  drawing  graphic  output  then  a  display  list  is  generated  for  a  Tek¬ 
tronix  4014  but  will  only  be  displayed  if  the  results  are  saved  with  SAVEMAP  and  then  re¬ 
displayed. 

The  flags  are  interpreted  as  follows: 

—  s  Don’t  print  any  of  the  monitor  messages,  including  prompts.  This  is  inclusive  of  the 

day  file. 

—d  Don't  print  the  dayfile. 

—  a  Disable  the  autoclear  function  in  the  terminal  monitor. 

-tr  Set  the  terminal  type  to  T.  T can  be  gt40,  gt42,  or  4014  for  DEC’s  GT40-GT42,  and 
Tektronix’s  4014  respectively. 

—  tnT  Do  not  display  output  but  prepare  the  display  list  for  a  terminal  of  type  T,  where  T'  is 

from  the  above  list. 

EXAMPLE 

geoquel  demo 

geoquel  —  d  demo 

geoquel  —s  demo  <  batchfile 

FILES 

..,/files/grafile6.2 

.../files/ttytype 

SEE  ALSO 

GEO-QUEL  reference  manual 
DIAGNOSTICS 

The  diagnostics  produced  by  GEO-QUEL  are  intended  to  be  self-explanatory.  Occasional  mes¬ 
sages  may  be  produced  by  Ingres;  for  an  explanation  of  these  messages  see  the  Ingres  system 
documentation. 
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NAME 

pnnir  —  print  relations 
\Opsis 

prinlr  [flags]  database  relation  ... 


DESCRIPTION 

Pnnir  prints  the  named  relation(s)  out  of  the  database  specified,  exactly  like  the  print  command. 
Retrieve  permission  must  be  granted  to  all  people  to  execute  this  command. 

Flags  accepted  are  — u,  ±w,  — c,  — i,  — f,  and  — v.  Their  meanings  are  identical  to  the  mean¬ 
ings  of  the  same  flags  in  Ingres. 


SEE  ALSO 

ingres(unix),  print(quel) 


DIAGNOSTICS 

bad  flag  —  you  have  specified  a  flag  which  is  not  legal  or  is  in  bad  format, 
you  may  not  access  database  —  this  database  is  prohibited  to  you  based  on  status  information  in 
the  users  file. 

cannot  access  database  —  the  database  does  not  exist. 
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\  \\n 

purge  -  destroy  all  expired  and  temporary  relations 
SYNOPSIS 

purge  [  — f  )  I  — p  )  [  — a  )  [  — s  )  [  ±w  ]  (  database  ...  ) 

DESCRIPTION 

Purge  searches  the  named  databases  deleting  system  temporary  relations.  When  using  the  —  p 
flag,  expired  user  relations  are  deleted.  The  — f  flag  will  cause  unrecognizable  files  to  be  delet¬ 
ed,  normally  purge  will  just  report  these  files. 

Only  the  database  administrator  (the  DBA)  for  a  database  may  run  purge,  except  the  INGRES 
superuser  may  purge  any  database  by  using  the  —  s  flag. 

If  no  databases  are  specified  all  databases  for  which  you  are  the  DBA  will  be  purged.  All  data¬ 
bases  will  be  purged  if  the  INGRES  superuser  has  specified  the  — s  flag.  The  —a  flag  will  cause 
purge  to  print  a  message  about  the  pending  operation  and  execute  it  only  if  the  response  if  a 
‘y\  Any  other  response  is  interpreted  as  i4no’\ 

Purge  will  lock  the  data  base  while  it  is  being  processed,  since  errors  may  occur  if  the  database 
is  active  while  purge  is  working  on  the  database.  If  a  data  base  is  busy  purge  will  report  this  and 
go  on  to  the  next  data  base,  if  any.  If  standard  input  is  not  a  terminal  purge  will  wait  for  the 
data  base  to  be  free.  If  —  w  flag  is  stated  purge  will  not  wait,  regardless  of  standard  input.  The 
+  w  flag  causes  purge  to  always  wait. 

EXAMPLES 

purge  —  p  +w  tempdata 
purge  —a  —  f 

SEE  ALSO 

save(quel),  restore(unix) 

D!  \G\OSTlCS 

who  are  you?  —  you  are  not  entered  into  the  users  file. 

not  ingres  superuser  -  you  have  tried  to  use  the  — s  flag  but  you  are  not  the  INGRES  su¬ 
peruser. 

you  are  not  the  dba  —  you  have  tried  to  purge  a  database  for  which  you  are  not  the  DBA. 
cannot  access  database  —  the  database  does  not  exist. 

BU.S 

If  no  database  names  are  given,  only  the  databases  located  in  the  directory  data/base  are 
purged,  and  not  the  old  databases  in  datadir.  Explicit  database  names  still  work  for  databases 
in  either  directory. 
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NAME 

restore  -  recover  from  an  INGRES  or  UNIX  crash. 

SWOPSIS 

restore  [  —a  ]  [  — s  1  I  ±w  ]  (  database  ...  I 
DESCRIPTION 

Restore  is  used  to  restore  a  data  base  after  an  INGRES  or  UNIX  crash.  It  should  always  be  run 
after  any  abnormal  termination  to  ensure  the  integrity  of  the  data  base. 

In  order  to  run  restore,  you  must  be  the  DBA  for  the  database  you  are  restoring  or  the  Ingres 
superuser  and  specify  the  — s  flag. 

If  no  databases  are  specified  then  all  databases  for  which  you  are  the  DBA  are  restored.  Ail  da¬ 
tabases  will  be  restored  if  the  INGRES  superuser  has  specified  the  —  s  flag. 

If  the  —a  flag  is  specified  you  will  be  asked  before  restore  takes  any  serious  actions.  It  is  advis¬ 
able  to  use  this  flag  if  you  suspect  the  database  is  in  bad  shape.  Using  /dev/null  as  input  with 
the  —a  flag  will  provide  a  report  of  problems  in  the  data  base.  If  there  were  no  errors  while 
restoring  a  database,  purge  will  be  called,  with  the  same  flags  that  were  given  to  restore,  to  re¬ 
move  unwanted  files  and  system  temporaries.  Restore  may  be  called  with  the  —  f  and/or  —  p 
flags  for  purge.  Unrecognized  files  and  expired  relations  are  not  removed  unless  the  proper 
flags  are  given.  In  the  case  of  an  incomplete  destroy,  create  or  index  restore  will  not  delete  files 
for  partially  created  or  destroyed  relations.  Purge  must  be  called  with  the  —  ff  flag  to  accomplish 
this. 

Restore  locks  the  data  base  while  it  is  being  processed.  If  a  data  base  is  busy  restore  will  report 
this  and  go  on  to  the  next  data  base.  If  standard  input  is  not  a  terminal  restore  will  wait  for  the 
data  base  to  be  free.  If  the  — w  flag  is  set  restore  will  not  wait  regardless  of  standard  input.  If 
+  w  is  set  it  will  always  wait. 

Restore  can  recover  a  database  from  an  update  which  had  finished  filling  the  batch  file.  Updates 
which  did  not  make  it  to  this  stage  should  be  rerun.  Similarly  modifies  which  have  finished  re¬ 
creating  the  relation  will  be  completed  (the  relation  relation  and  attribute  relations  will  be  up¬ 
dated).  If  a  destroy  was  in  progress  it  will  be  carried  to  completion,  while  a  create  will  almost- 
always  be  backed  out.  Destroying  a  relation  with  an  index  should  destroy  the  index  so  restore 
may  report  that  a  secondary  relation  has  been  found  with  no  primary. 

If  interrupt  (signal  2)  is  received  the  current  database  is  closed  and  the  next,  if  any,  is  pro¬ 
cessed.  Quit  (signal  3)  will  cause  restore  to  terminate. 

EXAMPLE 

restore  ~f  demo 

restore  -a  grants  <  /dev/null 

DIAGNOSTIC'S 

All  diagnostics  are  followed  by  a  tuple  from  a  system  relations. 

"No  relation  for  attribute (s) —  the  attributes  listed  have  no  corresponding  entry  in  the  rela¬ 
tion  relation 

"No  primary  relation  for  index”  —  the  tuple  printed  is  the  relation  tuple  for  a  secondary  index 
for  which  there  is  no  primary  relation.  The  primary  probably  was  destroyed  the 
secondary  will  be. 

"No  indexes  entry  for  primary  relation”  —  the  tuple  is  for  a  primary  relation,  the  rei  ndxd 
domain  will  be  set  to  zero.  This  is  the  product  of  an  incomplete  destroy. 

"No  indexes  entry  for  index”  —  the  tuple  is  for  a  secondary  index,  ihe  index  will  be  destroyed 
This  is  the  product  of  an  incomplete  destroy. 

"reiname  is  index  for”  -  an  index  has  been  found  for  a  primary  which  is  not  marked  ax  in- 
dexed.  The  primary  will  be  so  marked.  This  is  probably  the  product  of  an  incom¬ 
plete  index  command.  The  index  will  have  been  created  properly  but  not  modified 
"No  file  for”  -  There  is  no  data  for  this  relation  tuple,  the  tuple  will  be  deleted  If,  under  the 
—  a  option,  the  tuple  is  not  deleted  purge  will  not  be  called. 
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“No  secondary  index  for  indexes  entry"  —  An  entry  has  been  found  in  the  indexes  relation  for 
which  the  secondary  index  does  not  exist  (no  relation  relation  tuple).  The  entry  will 
be  deleted. 


SEt  ALSO 

purge(unix) 


BIGS 

If  no  database  names  are  given,  only  the  databases  located  in  the  directory  data/base  are  re¬ 
stored,  and  not  the  old  databases  in  datadir.  Explicit  database  names  still  work  for  databases  in 
either  directory. 
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\  \\l  Y 

sysmod  —  modify  system  relations  to  predetermined  storage  structures. 

SYNOPSIS 

sysmod  I  — s  )  I  — w  1  dbname  [  relation  ]  [  attribute  ]  (  indexes  ]  [  tree  ]  1  protect  ]  [  integri¬ 
ties  ] 

OKS(  KIPTION 

Sysmod  will  modify  the  relation,  attribute,  indexes,  tree,  protect,  and  integrities  relations  to 
hash  unless  at  least  one  of  the  relation,  attribute,  indexes,  tree,  protect,  or  integrities  parame¬ 
ters  are  given,  in  which  case  only  those  relations  given  as  parameters  are  modified.  The  system 
relations  are  modified  to  gain  maximum  access  performance  when  running  Ingres.  The  user 
must  be  the  data  base  administrator  for  the  specified  database,  or  be  the  inc. res  superuser  and 
have  the  — s  flag  stated. 

Sysmod  should  be  run  on  a  data  base  when  it  is  first  created  and  periodically  thereafter  to  main¬ 
tain  peak  performance.  If  many  relations  and  secondary  indices  are  created  and/or  destroyed, 
wsmod  should  be  run  more  often. 

If  the  data  base  is  being  used  while  sysmod  is  running,  errors  will  occur.  Therefore,  sysmod  will 
lock  the  data  base  while  it  is  being  processed.  If  the  data  base  is  busy,  sysmod  will  report  this. 
If  standard  input  is  not  a  terminal  sysmod  will  wait  for  the  data  base  to  be  free.  If  — w  flag  is 
stated  sysmod  will  not  wait,  regardless  of  standard  input.  The  +w  flag  causes  sysmod  to  always 
wait. 

The  system  relations  are  modified  to  hash;  the  relation  relation  is  keyed  on  the  first  domain, 
the  indexes,  attribute,  protect,  and  integrities  relations  are  keyed  on  the  first  two  domains,  and 
ihe  tree  relation  is  keyed  on  domains  one,  two,  and  five.  The  relation  and  attribute  relations 
have  the  minpages  option  set  at  10,  the  indexes  relation  has  a  minpages  value  of  5. 

sn  \l  so 

modify(quel) 


TIMEF1X  ( UNIX ) 


3/14/79 


T1MEFIX  ( UNIX  ) 


NAME 

timefix  —  patch  INGRES  binary  code  for  correct  timezone. 

NOPSIS 

timefix  [  — u  ]  (  —s N  ]  l  — t yyyzzz  ]  [  —&X  ]  filename  ... 

DESCRIPTION 

Timefix  can  be  used  to  change  the  Ingres  system  to  use  local  time.  As  delivered,  the  Ingres 
system  assumes  it  is  in  the  Pacific  Time  Zone,  eight  hours  behind  Greenwich  Mean  Time. 
Timefix  can  automatically  patch  the  necessary  INGRES  code  to  reflect  the  true  timezone  of  your 
installation. 

INGRES  uses  the  UNIX  supplied  routine  ctime(lll)  for  converting  the  UNIX  base  time  to  local 
time.  Timefix  is  first  compiled  on  your  system  in  order  to  get  the  clime  routine  for  your  installa¬ 
tion.  It  then  can  correct  the  necessary  INGRES  programs  at  which  point  your  INGRES  system  will 
be  correct  and  not  have  to  be  changed  again. 

To  use  timefix  you  must  be  logged  in  as  ingres  and  then  use  the  setup  command: 
setup  timefix 

This  command  performs  the  following  steps:  (1)  compiles  timefix. c,  (2)  runs  timefix  on  the 
necessary  INGRES  programs. 

If  for  any  reason,  timefix. c  cannot  be  compiled  on  your  system,  another  method  exists  for  up¬ 
dating  INGRES.  Timefix  can  be  run  with  the  local  time  expressed  using  the  —  s  — t  and  — d  flag 
options.  Their  meanings  are: 

—  s N  N  is  the  number  of  seconds  ahead/behind  GMT. 

— t yyyzzz  jyyand  zzzare  the  two,  three  character  timezone  names. 

-dX  if  X  is  0,  then  daylight  savings  time  is  disabled,  otherwise  daylight  savings  time 

will  occur  according  to  the  rules  specified  in  ctime(lll). 

The  flags  can  be  given  in  any  order.  You  must  be  logged  in  as  ingres  and  then  use  the  setup 
command  giving  the  proper  time  conversions.  For  example,  in  Hartford,  Connecticut  you 
would  type: 

setup  timefix  —  sl8000  -tESTEDT  — dl 

If  the  —  u  flag  is  specified  then  timefix  reports  what  it  would  do  but  does  not  actually  updaie  the 
files. 

EXAMPLES 

setup  timefix 

setup  timefix  —sl8000  — tESTEDT  — dl 
diagnostics 

Timefix  depends  on  the  existence  of  a  namelist.  If  the  namelist  (i.e.  symbol  table)  is  not 
present  then  an  error  message  is  given.  If  all  the  symbols  related  to  the  clime  routine  cannot  be 
found  then  it  is  assumed  that  the  file  need  not  be  corrected.  If  the  file  cannot  be  opened  for 
reading  and  writing  then  an  error  message  is  issued. 


Bi  us 

Timefix  will  not  work  for  timezones  which  are  ±  10  or  ±11  hours  from  GMT. 

si  I  \t  SO 

cnmc(III) 
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NAME 

usersetup  —  setup  users  file 
SYNOPSIS 

.../bin/usersetup  l  pathname  1 
DESCRIPTION 

The  /etc/passwd  file  is  read  and  reformatted  to  become  the  INGRES  users  file,  stored  into 
.../fifes/users.  If  pathname  is  specified,  it  replaces  If  pathname  is  the  result  is 

written  to  the  standard  output. 

The  user  name,  user,  and  group  id’s  are  initialized  to  be  identical  to  the  corresponding  entry  in 
the  /etc/passwd  file.  The  status  field  is  initialized  to  be  zero,  except  for  user  ingres,  which  is 
initialized  to  all  permission  bits  set.  The  “initialization  file”  parameter  is  set  to  the  file  .Ingres 
in  the  user’s  login  directory.  The  user  code  field  is  initialized  with  sequential  two-character 
codes.  All  other  fields  are  initialized  to  be  null. 

After  running  usersetup,  the  users  file  must  be  edited.  Any  users  who  are  to  have  any  special 
authorizations  should  have  the  status  field  changed,  according  to  the  specifications  in 
users(files).  To  disable  a  user  from  executing  INGRES  entirely,  completely  remove  her  line 
from  the  users  file. 

As  UNIX  users  are  added  or  deleted  from  the  /etc/passwd  file,  the  users  file  will  need  to  be 
editted  to  reflect  the  changes.  For  deleted  users,  it  is  only  necessary  to  delete  the  line  for  that 
user  from  the  users  file.  To  add  a  user,  you  must  assign  that  user  a  code  in  the  form  "aa"  and 
enter  a  line  in  the  users  file  in  the  form: 

name:cc:uid:gid:status:flags:proctab:initfiIe::databases 
where  name  is  the  user  name  (taken  from  the  first  field  of  the  /etc/passwd  file  entry  for  this 
user),  vc  is  the  user  code  assigned,  which  must  be  exactly  two  characters  long  and  must  not  be 
the  same  as  any  other  existing  user  codes,  wet  and  gid  are  the  user  and  group  ids  (taken  from 
the  third  and  fourth  fields  in  the  /etc/passwd  entry),  status  is  the  status  bits  for  this  user,  nor¬ 
mally  000000,  flags  are  the  default  flags  for  INGRES  (on  a  per-user  basis),  proctab  is  the  default 
process  table  for  this  user  (which  defaults  to  =proctab6.2),  and  databases  is  a  list  of  the  data¬ 
bases  this  user  may  enter.  If  null,  she  may  use  all  databases.  If  the  first  character  is  a  dash 
the  field  is  a  comma  separated  list  of  databases  which  she  may  not  enter.  Otherwise,  it 
is  a  list  of  databases  which  she  may  enter. 

The  databases  field  includes  the  names  of  databases  which  may  be  created. 

Usersetup  may  be  executed  only  once,  to  initially  create  the  users  file. 


FILES 

.../files/users 

/etc/passwd 

SEE  ALSO 

ingres(unix),  passwd(V),  users(files) 
it  should  be  able  to  bring  the  users  file  up  to  date. 


BIOS 
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NAME 

./files/dayfile6.1  -  Ingres  login  message 
DESCRIPTION 

The  contents  of  the  dayfile  reflect  user  information  of  general  system  interest,  and  is  more  or 
less  analogous  to  /etc/motd  in  UNIX.  The  file  has  no  set  format;  it  is  simply  copied  at  login 
lime  to  the  standard  output  device  by  the  monitor  if  the  —s  or  —  d  options  have  not  been  re¬ 
quested.  Moreover  the  dayfile  is  not  mandatory,  and  its  absence  will  not  generate  errors  of  any 
sort;  the  same  is  true  when  the  dayfile  is  present  but  not  readable. 


DBTMPLTt  FILES) 
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\  wit 

./files/dbtmplt6.2  -  database  template 
DESCRIPTION 

This  file  contains  the  template  for  a  database  used  by  creatdb.  It  has  a  set  of  entries  for  each 
relation  to  be  created  in  the  database.  The  sets  of  entries  are  separated  by  a  blank  line.  Two 
blank  lines  or  an  end  of  file  terminate  the  file. 

The  first  line  of  the  file  is  the  database  status  and  the  default  relation  status,  separated  by  a 
colon.  The  rest  of  the  file  describes  relations.  The  first  line  of  each  group  gives  the  relation 
name  followed  by  an  optional  relation  status,  separated  by  a  colon.  The  rest  of  the  lines  in  each 
group  are  the  attribute  name  and  the  type,  separated  by  a  tab  character. 

All  the  status  fields  are  given  in  octal,  and  have  a  syntax  of  a  single  number  followed  by  a  list 
of  pairs  of  the  form 
±x±N 

which  says  that  if  the  ±  x  flag  is  asserted  on  the  creatdb  command  line  then  set  (clear)  the  bits 
specified  by  N. 

The  first  set  of  entries  must  be  for  the  relation  catalog,  and  the  second  set  must  be  for  the  attri¬ 
bute  catalog. 

EXAMPLE 

3  —  c —  1  +  q +  2:010023 
relation:  —  c  —  20 
relid  cl  2 

relowner  c2 

relspec  il 

attribute:-c  — 20 
attrelid  cl 2 
attowner  c2 

attnamec!2 

(other  relation  descriptors) 

SEE  ALSO 

creatdb(unix) 
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WMK 

.../files/error6.2_?  —  file*  with  jngrfs  errors 
DESCRIPTION 

These  files  contain  the  INGRES  error  messages.  There  is  one  file  for  each  thousands  digit; 
hence,  error  number  2313  will  be  in  file  error6.2_2. 

Each  file  consists  of  a  sequence  of  error  messages  with  associated  error  numbers.  When  an  er¬ 
ror  enters  the  front  end,  the  appropriate  file  is  scanned  for  the  correct  error  number.  If  found, 
the  message  is  printed;  otherwise,  the  first  message  parameter  is  printed. 

Each  message  has  the  format 

ermum  <TAB>  message  tilde. 

Messages  are  terminated  by  the  tilde  character  0*’).  The  message  is  scanned  before  printing. 
If  the  sequence  is  encountered  (where  n  is  a  digit  from  0  to  9),  parameter  n  is  substituted, 
where  %0  is  the  first  parameter. 

The  parameters  can  be  in  any  order.  For  example,  an  error  message  can  reference  %2  before  it 
references  %0. 


SEE  ALSO 

error(UTIL) 

EXAMPLE 

1003  line  %0,  bad  database  name  %1~ 

1005  In  the  purge  of  %1, 

a  bad  %0  caused  execution  to  halt*" 

1006  No  process,  try  again." 
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wmi: 

./filcs/grafile6.2  -  geo-quel  login  message 

DEM  R I  PI  ION 

The  contents  of  the  grafile  (GEO-QUEL  dayfile)  reflect  user  information  of  general  system  in¬ 
terest,  and  is  more  or  less  analogous  to  /etc/motd  in  UNIX.  The  file  has  no  set  format;  it  is 
simply  copied  at  login  lime  to  the  standard  output  device  by  GEO-QUEL  if  the  —  s  or  —  d  options 
have  not  been  requested.  Moreover  the  grafile  is  not  mandatory,  and  its  absence  will  not  gen¬ 
erate  errors  of  any  sort;  the  same  is  true  when  the  grafile  is  present  but  not  readable. 
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NAME 

libq  —  Equel  run-time  support  library 
DESCRIPTION 

Libq  all  the  routines  necessary  for  an  equel  program  to  load.  It  resides  in  /lib/libq.a,  and  must 
be  specified  when  loading  equel  pre-processed  object  code.  It  may  be  referenced  on  the  com¬ 
mand  line  of  cc  by  the  abbreviation  — lq. 

Several  useful  routines  which  are  used  by  equel  processes  are  included  in  the  library.  These 
may  be  employed  by  the  equel  programmer  to  avoid  code  duplication.  They  are; 

ini  llatoi(buf,  i) 

char  *buf; 
ini  i; 

char  *llbmove(source,  destination,  len) 
char  ‘source,  ‘destination; 
int  len; 

char  *IIconcatv(buf,  argl,  arg2,  0) 
char  *buf,  ‘argl,  ...; 

char  *Uitos(i) 
int  i; 

int  NsequaKsl,  s2) 

char  ‘si,  *s2; 

int  Ulength(siring) 

char  ‘string; 

llsyserr(string,  argl,  arg2,  ...); 
char  ‘string; 

llatoi  Ilatoi  is  equivalent  to  atoi(UTlL). 

Ubmove  Moves  len  bytes  from  source  to  destination ,  returning  a  pointer  to  the  location  after 

the  last  byte  moved.  Does  not  append  a  null  byte. 

Ilconcalv  Concatenates  into  buf  ail  of  its  arguments,  returning  a  pointer  to  the  null  byte  at 
the  end  of  the  concatenation.  Buf  may  not  be  equal  to  any  of  the  arg-n  but  argl. 

Uitos  llitos  is  equivalent  to  itoa(UI). 

Ilsequal  Returns  1  iff  strings  si  is  identical  to  s2. 

lllength  Returns  maxdength  of  string  without  null  byte  at  end,  255) 

Ihtscrr  Hsyserr  is  diferrent  from  syserr(uiil)  only  in  that  it  will  print  the  name  in 

llproc_name,  and  in  that  there  is  no  0  mode.  Also,  it  will  always  call  exitl-1) 
after  printing  the  error  message. 

There  are  also  some  global  Equel  variables  which  may  be  manipulated  by  the  user; 


mt 

llerrfiag; 

char 

*llmainpr; 

char 

I*l!print_err)0 

ini 

HreterrO; 

ini 

llnoerr  ( > : 
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llcrrtlag  Set  on  an  error  from  INGRES  to  be  the  error  number  (see  the  error  message  sec¬ 
tion  of  the  “Ingres  Reference  Manual")  that  ocurred.  This  remains  valid  from 
the  time  the  error  occurrs  to  the  lime  when  the  next  equel  statement  is  issued. 
This  may  be  used  just  after  an  equel  statement  to  see  if  it  succeded. 

Umainpr  This  is  a  string  which  determines  which  ingres  to  call  when  a  "##  ingres*  is  is¬ 
sued.  Initially  it  is  ’yusr/bin/ingres". 

Ilprinterr  This  function  pointer  is  used  to  call  a  function  which  determines  what  (if  any)  er¬ 
ror  message  should  be  printed  when  an  ingres  error  occurs.  It  is  called  from  Iler- 
rorO  with  the  error  number  as  an  argument,  and  the  error  message  corresponding 
to  the  error  number  returned  will  be  printed.  If  (*IIprint_err)(  <ermo»  returns 
0,  then  no  error  message  will  be  printed.  Initially  IIprint_err  is  set  to  Ilret  errO 
to  print  the  error  that  ocurred. 

IIret_err  Returns  its  single  integer  argument.  Used  to  have  (*IIprint_err)()  cause  printing 
of  the  error  that  ocurred. 

Uno_err  Returns  0.  Used  to  have  (*llprint_err)0  suppress  error  message  printing. 

IIno_err  is  used  when  an  error  in  a  parametrized  equel  statemenr  occurs  to 
suppress  printing  of  the  corresponding  parser  error. 

SEE  ALSO 

atoi(util),  bmove(util)1  cc(I),  equei(unix),  exit(II),  itoa(III),  length(util),  sequal(util), 

syserr(util) 
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NAME 

./files/proctab6.2  -  INGRES  runtime  configuration  information 
DESCRIPTION 

The  file  .../files/proctab6.2  describes  the  runtime  configuration  of  the  Ingres  system. 

The  process  table  is  broken  up  into  logical  sections,  separated  by  lines  with  a  single  dollar  sign. 
The  first  section  describes  the  configuration  of  the  system  and  the  parameters  to  pass  to  each 
system  module.  All  other  sections  contain  strings  which  may  be  macro-substituted  into  the  first 
section. 

Each  line  of  the  first  section  describes  a  single  process.  The  lines  consist  of  a  series  of  colon- 
separated  fields. 

The  first  field  contains  the  pathname  of  the  module  to  be  executed. 

The  second  field  is  a  set  of  flags  which  allow  the  line  to  be  ignored  in  certain  cases.  If  this  field 
is  null,  the  line  is  accepted;  otherwise,  it  should  be  a  series  of  items  of  the  form  — =A"\ 
where  any  of  “  +  —  may  be  omitted,  and  A'  is  a  flag  which  may  appear  on  the  Ingres  com¬ 
mand  line.  The  characters  are  interpreted  as  the  sense  of  the  flag:  “  +  ”  will  accept 

the  line  if  the  flag  "  +  X"  is  stated  on  the  command  tine,  “  — "  will  accept  i f  “  —  X  ”  is  stated, 
and  “  —  "  will  accept  if  the  “X"  flag  is  not  stated  at  all.  These  may  be  combined  in  the  forms 
“  +  — ”  and  “  —  For  example,  the  field: 

+  =& 

will  acept  the  line  if  the  EQUEL  flag  (“&M)  is  stated  as  “  +  &"  or  is  not  stated,  but  the  line  will 
be  ignored  if  the  “  —  flag  is  stated. 

If  any  flag  item  rejects  the  line,  the  entire  line  is  rejected. 

The  third  field  is  a  status  word.  The  number  in  this  word  is  expressed  in  octal.  The  bits  have 
the  following  meaning: 

000010  close  diagnostic  output 

000004  close  standard  input 

000002  run  in  user’s  directory,  not  database 

000001  run  as  the  user,  not  as  INGRES 

The  fourth  field  is  a  file  name  to  which  the  standard  output  should  be  redirected.  It  is  useful 
for  debugging. 

The  fifth  field  describes  the  pipes  which  should  be  connected  to  this  process.  The  field  must  be 
six  characters  long,  with  the  characters  corresponding  to  the  internal  variables  R_up,  W_up, 
R  down,  W  down,  R  front,  and  W  front  respectively.  The  characters  may  be  a  question  mark, 
which  leaves  the  pipe  closed;  a  digit,  which  is  filled  in  from  the  file  descriptors  provided  by  the 
EQUEL  flag  or  the  flag;  or  a  lower  case  letter,  which  is  connected  via  a  pipe  with  any  oth¬ 
er  pipes  having  the  same  letter;  this  last  action  is  done  on  the  fly  to  conserve  file  descriptors. 

The  sixth  and  subsequent  fields  are  arbitrary  parameters  to  be  sent  to  the  modules.  There  must 
be  a  colon  after  the  fifth  field  even  if  no  parameters  are  present,  but  there  need  not  be  a  colon 
after  the  last  parameter. 

The  last  module  executed  (usually  the  last  line  in  the  first  section!  becomes  the  parent  of  all 
the  other  processes. 

The  second  through  last  sections  of  the  process  table  consist  of  a  single  line  which  names  ihe 
section  followed  by  arbitrary  text.  The  pathname  field  and  all  parameter  fields  of  each  line  of 
the  first  section  are  scanned  for  strings  of  the  form  *’Sname“;  this  string  is  replaced  by  the  text 
from  the  corresponding  section.  For  convenience,  the  name  Spathname  is  automaticalls 
defined  to  be  the  pathname  of  the  root  of  the  INGRES  subtree. 

The  DBU  routines  want  to  see  two  parameters.  The  first  parameter  is  the  pathname  of  the 
“ksori  ’  routine.  The  second  parameter  is  a  series  of  lines  of  the  form. 
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commandname  place Jist 

where  command  name  is  the  name  of  one  of  the  possible  INGRES  commands  executed  by  the 
DHL1  routines,  and  place  Jist  is  a  comma-separated  list  of  the  actual  location  (s)  of  that  com¬ 
mand.  Each  “place"  is  a  two-character  descriptor:  the  first  character  is  the  overlay  in  which 
that  command  resides,  and  the  second  character  is  the  function  within  that  overlay.  If  a  com¬ 
mand  is  in  more  than  one  place,  INGRES  will  try  to  avoid  calling  in  another  overlay.  For  exam¬ 
ple: 

create:aO,ml 

means  that  the  create  command  may  be  found  in  overlay  "a”  function  0  or  in  overlay  “m" 
function  1.  If  already  in  overlay  “a"  or  "m"  the  create  command  resident  in  that  overlay  will 
be  called;  otherwise,  overlay  "a"  will  be  called. 

EXAMPLE 

The  following  example  will  execute  a  three  process  system  unless  the  flag  is  specified  (as 
“  —  when  a  two-process  system  will  be  executed  with  the  monitor  dropped  out  and  the  cal¬ 
ling  (EQUEL)  program  in  its  place.  Notice  that  there  are  two  lines  for  the  parser  entry,  one  for 
the  EQUEL  case  and  one  for  the  non-EQUEL  case.  In  the  EQUEL  case,  output  from  the 
parser  is  diverted  to  a  file  called  “debug.out". 

!  $paihname/bin/o  verlaya:  :0000 14::bc?  ?  23  :$pathname/bin/ksort:$dbutab 

$pathname/bin/parser:  +  !=&:0000I4::adcb??: 

Spathname/bin/parser:  — &:000014:debug.out:01cb??: 

$pathname/bin/monitor:  +  =*&:000003::??da??:$pathname/files/startup 
$ 

dbutab 

create:aO,ml 

destroy  :a  I, m2 

modify.mO 

help:a2 

$ 
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../files/startup  —  INGRES  startup  file 
DESCRIPTION 

This  file  is  read  by  the  monitor  at  login  time.  It  is  read  before  the  user  startup  file  specified  in 
the  users  file.  The  primary  purpose  is  to  define  a  new  editor  and/or  shell  to  call  with  the  \e  or 
\s  commands. 

SEE  AI.SO 

monitor(quel),  users(files) 
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\  w  n 

Vtiles/iiyt>  pc  -  geo-qi  El  terminal  type  database 
UK.SC  RIPTION 

The  ttytype  file  describes  each  terminal  on  your  system,  geo-quel  will  not  attempt  to  display 
graphical  output  on  terminals  that  are  not  capable  of  displaying  it.  There  is  a  sample  of  the  file 
in  .../{’eoquel/ttytype.sample.  This  is  a  copy  of  the  file  in  use  on  the  Berkeley  system. 

The  ttytype  file  consists  of  a  series  of  lines;  the  first  character  is  the  terminal  id,  and  the  rest  of 
the  line  tells  the  type  of  the  terminal.  The  first  of  these  characters  is  a  terminal  class,  and  the 
re^t  signify  the  brand,  or  some  other  more  descriptive  indication.  A  completely  blank  line  ter¬ 
minates  the  useful  part  of  the  file,  after  which  comments  may  appear  unrestricted.  In  the  sam¬ 
ple  file  the  currently  recognized  (defined)  terminal  types  are  listed  as  comments. 


BUiS 

The  current  version  of  geo-quel  only  looks  for  terminals  of  graphic  nature  and  therefore  only 
the  graphic  terminals  need  be  in  this  database.  If  any  other  system  or  sub-system  wishes  to  use 
this  file,  all  terminals  must  be  kept  up  to  date. 
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.  ./tiles/users  -  INGRES  user  codes  and  parameters 
DESCRIPTION 

This  file  contains  the  user  information  in  fields  seperated  by  colons.  The  fields  are  as  follows: 

*  User  name,  taken  directly  from  /etc/passwd  file. 

*  User  code,  assigned  by  the  INGRES  super-user.  It  must  be  a  unique  two  character  code. 

*  UNIX  user  id.  This  MUST  match  the  entry  in  the  /etc/passwd  file. 

*  UNIX  group  id.  Same  comment  applies. 

*  Status  word  in  octal.  Bit  values  are: 

0000001  creatdb  permission 

0000002  permits  batch  update  override 

0000004  permits  update  of  system  catalogs 

0000020  can  use  trace  flags 

0000040  can  turn  off  qrymod 

0000100  can  use  arbitrary  proctabs 

0000200  can  use  the  =proctab  form 

0100000  ingres  superuser 

*  A  list  of  flags  automatically  set  for  this  user. 

*  The  process  table  to  use  for  this  user. 

*  An  initialization  file  to  read  be  read  by  the  monitor  at  login  lime. 

*  Unassigned. 

*  Comma  seperated  list  of  databases.  If  this  list  is  null,  the  user  may  enter  any  database.  If  it 

begins  with  a  k  —  \  the  user  may  enter  any  database  except  the  named  databases.  Oth¬ 
erwise,  the  user  may  only  enter  the  named  databases. 

EXAMPLE 

ingres:aa:5:2: 177777:  ~d:  =  special.7mnt/ingres/.  ingres:: 
guest:ah:35:l:000000:::::demo,guest 

SEE  ALSO 

initucode(util) 
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name 

Error  messages  introduction 
DESCRIPTION 

This  document  describes  the  error  returns  which  are  possible  from  the  INGRES  data  base  system 
and  gives  an  explanation  of  the  probable  reason  for  their  occurrence.  In  all  cases  the  errors  are 
numbered  nxxx  where  n  indicates  the  source  of  the  error,  according  to  the  following  table: 

1  —  equel  preprocessor 

2  *  parser 

3  ”  query  modification 

4  —  decomposition  and  one  variable  query  processor 

5  —  data  base  utilities 
30  -  GEO-QUEL  errors 

For  a  description  of  these  routines  the  reader  is  referred  to  The  Design  and  Implementation  of 
INGRES.  The  xxx  in  an  error  number  is  an  arbitrary  identifier. 

The  error  messages  are  stored  in  the  file  .../flles/error6.2_n,  where  n  is  defined  as  above.  The 
format  of  these  files  is  the  error  number,  a  tab  character,  the  message  to  be  printed,  and  the 
tilde  character  to  delimit  the  message. 

In  addition  many  error  messages  have  “%/"  in  their  body  where  i  is  a  digit  interpreted  as  an 
offset  into  a  list  of  parameters  returned  by  the  source  of  the  error.  This  indicates  that  a  param¬ 
eter  will  be  inserted  by  the  error  handler  into  the  error  return.  In  most  cases  this  parameter 
will  be  self  explanatory  in  meaning. 

Where  the  error  message  is  thought  to  be  completely  self  explanatory,  no  additional  description 
is  provided. 
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NAME 

EQUEL  error  message  summary 
SYNOPSIS 

Error  numbers  1000  —  1999. 
bESCRIPTION 

The  following  errors  can  be  generated  at  run  time  by  EQUEL  programs. 

ERRORS 

1000  In  domain  %0  numeric  retrieved  into  char  field. 

Equel  does  not  support  conversion  at  run-time  of  numeric  data  from  the  data  base  to 
character  string  representation.  Hence,  if  you  attempt  to  assign  a  domain  of  numeric 
type  to  a  C-variabie  of  type  character  string,  you  will  get  this  error  message.  To  con¬ 
vert  numerics  to  characters  use  the  "ascii"  function  in  quel. 

1001  Numeric  overflow  during  retrieve  on  domain  %0.  < 

You  will  get  this  error  if  you  attempt  to  assign  a  numeric  data  base  domain  to  a  C- 
variable  of  a  numeric  type  but  with  a  shorter  length.  In  this  case  the  conversion 
routines  may  generate  an  overflow.  For  example,  this  error  will  result  from  an  attempt 
to  retrieve  a  large  floating  point  number  into  a  C-variable  of  type  integer. 

1002  In  domain  %0,  character  retrieved  into  numeric  variable. 

This  error  is  the  converse  of  error  1000. 

1003  Bad  type  in  target  list  of  parameterized  retrieve  "%0". 

Valid  types  are  %f8,  %f4,  %i4,  %i2,  %c. 

1004  Bad  type  in  target  list  of  parameterized  statement  "%0". 

Valid  types  are  %f8,  %f4,  %i4,  %i2,  %il,  %c. 
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name 

Parser  error  message  summary 
SYNOPSIS 

Error  numbers  2000  -  2999. 

DESCRIPTION 

The  following  errors  can  be  generated  by  the  parser.  The  parser  reads  your  query  and  translates 
it  into  the  appropriate  internal  form:  thus,  almost  all  of  these  errors  indicate  syntax  or  type 
conflict  problems. 

ERRORS 

2100  line  %0,  Attribute  '%!'  not  in  relation  '%2' 

This  indicates  that  in  a  given  line  of  the  executed  workspace  the  indicated  attribute 
name  is  not  a  domain  in  the  indicated  relation. 

2103  line  %0,  Function  type  does  not  match  type  of  attribute  ’%!' 

This  error  will  be  returned  if  a  function  expecting  numeric  data  is  given  a  character 
string  or  vice  versa.  For  example,  it  is  illegal  to  take  the  SIN  of  a  character  domain. 

2106  line  %0,  Data  base  utility  command  buffer  overflow 

This  error  will  result  if  a  utility  command  is  too  long  for  the  buffer  space  allocated  to  it 
in  the  parser.  You  must  shorten  the  command  or  recompile  the  parser. 

2107  line  %0,  You  are  not  allowed  to  update  this  relation:  %1 

This  error  will  be  returned  if  you  attempt  to  update  any  system  relation  or  secondary 
index  directly  in  QUEL  (such  as  the  RELATION  relation).  Such  operations  which 
compromise  the  integrity  of  the  data  base  are  not  allowed. 

2108  line  %0,  Invalid  result  relation  for  APPEND  *%1' 

This  error  message  will  occur  if  you  execute  an  append  command  to  a  relation  that 
does  not  exist,  or  that  you  cannot  access.  For  example,  append  to  junk(  ...  )  will  fail  if 
junk  does  not  exist. 

2109  line  %0,  Variable  *%1'  not  declared  in  RANGE  statement 

Here,  a  symbol  was  used  in  a  QUEL  expression  in  a  place  where  a  tuple  variable  was 
expected  and  this  symbol  was  not  defined  via  a  RANGE  statement. 

2111  line  %0,  Too  many  attributes  in  key  for  INDEX 

A  secondary  index  may  have  no  more  than  6  keys. 

2117  line  %0,  Invalid  relation  name  '%!'  in  RANGE  statement 

You  are  declaring  a  tuple  variable  which  ranges  over  a  relation  which  does  not  exist. 

2118  line  %0,  Out  of  space  in  query  tree  -  Query  too  long 

You  have  the  misfortune  of  creating  a  query  which  is  too  long  for  the  parser  to  digest. 
The  only  options  are  to  shorten  the  query  or  recompile  the  parser  to  have  more  buffer 
space  for  the  query  tree. 

2119  line  %0,  MOD  operator  not  defined  for  floating  point  or  character  attributes 
The  mod  operator  is  only  denned  for  integers. 

2120  line  %0,  no  pattern  match  operators  allowed  in  the  target  list 

Pattern  match  operators  (such  as  “*")  can  only  be  used  in  a  qualification. 

2121  line  %0.  Only  character  type  domains  are  allowed  in  CONCAT  operator 
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2123  line  %0,  '%l.alf  not  defined  for  replace 

2125  line  %0.  Cannot  use  aggregates  ("avg"  or  "avgu")  on  character  values 

2126  line  %0.  Cannot  use  aggregates  (’sum’'  or  'sumu")  on  character  values 

2127  line  %0.  Cannot  use  numerical  functions  (ATAN,  COS,  GAMMA,  LOG,  SIN,  SQRT, 
EXP.  ABS)  on  character  values 

2128  line  %0,  Cannot  use  unary  operators  ("+"  or  "-")  on  character  values 

2129  line  %0,  Numeric  operations  (+  —  *  /)  not  allowed  on  character  values 

Many  functions  and  operators  are  meaningless  when  applied  to  character  values. 

2130  line  %0,  Too  many  result  domains  in  target  list 

Maximum  number  of  result  domains  is  MAXDOM  (currently  49). 

2132  line  %0,  Too  many  aggregates  in  this  query 

Maximum  number  of  aggregates  allowed  in  a  query  is  MAXAGG  (currently  49) . 

2133  line  %0.  Type  conflict  on  relational  operator 

It  is  not  legal  to  compare  a  character  type  to  a  numeric  type. 

2134  line  %0.  *%1*  is  not  a  constant  operator. 

Only  'dba'  or  'usercode'  are  allowed. 

2135  line  %0,  You  cannot  duplicate  the  name  of  an  existing  relation (%1) 

You  have  tried  to  create  a  relation  which  would  redefine  an  existing  relation.  Choose 
another  name. 

2136  line  %0,  There  is  no  such  hour  as  %1,  use  a  24  hour  clock  system 

2137  line  %0,  There  is  no  such  minute  as  %1,  use  a  24  hour  clock  system 

2138  line  %0,  There  is  no  such  time  as  24:%1.  use  a  24  hour  clock  system 

Errors  2136-38  indicate  that  you  have  used  a  bad  time  in  a  permit  statement.  Legal 
times  are  from  0:00  to  24:00  inclusive. 

2139  line  %0,  Your  database  does  not  support  query  modification 

You  have  tried  to  issue  a  query  modification  statement  (define),  but  the  database  was 
created  with  the  *~q  flag.  To  use  the  facilities  made  available  by  query  modification, 
you  must  say: 

creatdb  —  e  +q  dbname 

to  the  shell. 

2500  syntax  error  on  line  %0 
last  symbol  read  was:  %1 

A  2500  error  is  reported  by  the  parser  if  it  cannot  otherwise  classify  the  error.  One 
common  way  to  obtain  this  error  is  to  omit  the  required  parentheses  around  the  target 
list.  The  parser  reports  the  last  symbol  which  was  obtained  from  the  scanner.  Some¬ 
times,  the  last  symbol  is  far  ahead  of  the  actual  place  where  the  error  occurred.  The 
string  ’EOF  is  used  for  the  last  symbol  when  the  parser  has  read  past  the  query. 

2502  line  %0,  The  word  cannot  follow  a  RETRIEVE  command,  therefore  the  com¬ 
mand  was  not  executed. 

2503  line  %0,  The  word  '%1\  cannot  follow  an  APPEND  command,  therefore  the  command 
was  not  executed. 

2504  line  %0,  The  word  cannot  follow  a  REPLACE  command,  therefore  the  command 

was  not  executed. 

2505  line  %0,  The  word  '%1\  cannot  follow  a  DELETE  command,  therefore  the  command 
was  not  executed. 

2506  line  %0.  The  word  *%1\  cannot  follow  a  DESTROY  command,  therefore  the  com¬ 
mand  was  not  executed. 

2507  line  %0.  The  word  cannot  follow  a  HELP  command,  therefore  the  command  was 
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not  executed. 

2508  line  %0,  The  word  '%1\  cannot  follow  a  MODIFY  command,  therefore  the  command 
was  not  executed. 

2509  line  %0,  The  word  cannot  follow  a  PRINT  command,  therefore  the  command 
was  not  executed. 

2510  line  %0,  The  word  '%1\  cannot  follow  a  RETRIEVE  UNIQUE  command,  therefore 
the  command  was  not  executed. 

2511  line  %0,  The  word  cannot  follow  a  DEFINE  VIEW  command,  therefore  the 
command  was  not  executed. 

2512  line  %0.  The  word  *%1\  cannot  follow  a  HELP  VIEW,  HELP  INTEGRITY,  or  HELP 
PERMIT  command,  therefore  the  command  was  not  executed. 

2513  line  %0,  The  word  '%I\  cannot  follow  a  DEFINE  PERMIT  command,  therefore  the 
command  was  not  executed. 

2514  line  %0,  The  word  *%1\  cannot  follow  a  DEFINE  INTEGRITY  command,  therefore 
the  command  was  not  executed. 

2515  line  %0.  The  word  *%1',  cannot  follow  a  DESTROY  INTEGRITY  or  DESTROY  PER¬ 
MIT  command,  therefore  the  command  was  not  executed. 

Errors  2502  through  2515  indicate  that  after  an  otherwise  valid  query,  there  was  some¬ 
thing  which  could  not  begin  another  command.  The  query  was  therefore  aborted, 
since  this  could  have  been  caused  by  misspelling  where  or  something  equally  as 
dangerous. 

2700  line  %0,  non-terminated  string 

You  have  omitted  the  required  string  terminator  C). 

2701  line  %0.  string  too  long 

Somehow,  you  have  had  the  persistence  or  misfortune  to  enter  a  character  string  con¬ 
stant  longer  than  255  characters. 

2702  line  %0,  invalid  operator 

You  have  entered  a  character  which  is  not  alphanumeric,  but  which  is  not  a  defined 
operator,  for  example,  *?’. 

2703  line  %0,  Name  too  long  *%1* 

In  INGRES  relation  names  and  domain  names  are  limited  to  1 2  characters. 

2704  line  %0,  Out  of  space  in  symbol  table  -  Query  too  long 

Your  query  is  too  big  to  process.  Try  breaking  it  up  with  more  \go  commands. 

2705  line  %0,  non-terminated  comment 

You  have  left  off  the  comment  terminator  symbol  <**•/”). 

2707  line  %0,  bad  floating  constant:  %1 

Either  your  floating  constant  was  incorrectly  specified  or  it  was  too  large  or  too  small. 
Currently,  overflow  and  underflow  are  not  checked. 

2708  line  %0,  control  character  passed  in  pre-converted  siring 

In  EQt'EL  a  control  character  became  embedded  in  a  string  and  was  not  caught  until  the 
scanner  was  processing  it. 

2709  line  %0,  buffer  overflow  in  converting  a  number 

Numbers  cannot  exceed  256  characters  in  length.  This  shouldn't  become  a  problem 
until  number  formats  in  INGRES  are  increased  greatly. 
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NAME 

Query  Modification  error  message  summary 
SYNOPSIS 

Error  numbers  3000  —  3999. 

DESCRIPTION 

These  error  messages  are  generated  by  the  Query  Modification  module.  These  errors  include 
syntactic  and  semantic  problems  from  view,  integrity,  and  protection  definition,  as  well  as  run 
time  errors  —  such  as  inability  to  update  a  view,  or  a  protection  violation. 

ERRORS 

3310  %0  on  view  %1:  cannot  update  some  domain 

You  tried  to  perform  operation  %0  on  a  view:  however,  that  update  is  not  defined. 

3320  %0  on  view  %1:  domain  occurs  in  qualification  of  view 

It  is  not  possible  to  update  a  domain  in  the  qualification  of  a  view,  since  this  could 
cause  the  tuple  to  disappear  from  the  view. 

3330  %o  on  view  %1:  update  would  result  in  more  than  one  query 

You  tried  to  perform  some  update  on  a  view  which  would  update  two  underlying  rela¬ 
tions. 

3340  %0  on  view  %1:  views  do  not  have  TID’s 

You  tried  to  use  the  Tuple  IDentifier  field  of  a  view,  which  is  undefined. 

3350  %0  on  view  %1:  cannot  update  an  aggregate  value 

You  cannot  update  a  value  which  is  defined  in  the  view  definition  as  an  aggregate. 

3360  %0  on  view  %1 :  that  update  might  be  non- functional 

There  is  a  chance  that  the  resulting  update  would  be  non-functional,  that  is.  that  it 
may  have  some  unexpected  side  effects.  INGRES  takes  the  attitude  that  it  is  better  to 
not  try  the  update. 

3490  INTEGRITY  on  %1:  cannot  handle  aggregates  yet 

You  cannot  define  integrity  constraints  which  include  aggregates. 

3491  INTEGRITY  on  %1:  cannot  handle  multivariable  constraints 

You  cannot  define  integrity  constraints  on  more  than  a  single  variable. 

3492  INTEGRITY  on  %1:  constraint  does  not  initially  hold 

When  you  defined  the  constraint,  there  were  already  tuples  in  the  relation  which  did 
not  satisfy  the  constraint.  You  must  fix  the  relation  so  that  the  constraint  holds  before 
you  can  declare  the  constraint. 

3493  INTEGRITY  on  %t :  is  a  view 

You  can  not  define  integrity  constraints  on  views. 

3494  INTEGRITY  on  %  1 :  You  must  own  '%  I ' 

You  must  own  the  relation  when  you  declare  integrity  constraints. 

3S00  %0  on  relation  %l:  protection  violation 

You  have  tried  to  perform  an  operation  which  is  not  permitted  to  you. 

3S90  PERMIT:  bad  terminal  identifier  "%2" 

In  a  permit  statement,  the  terminal  identifier  field  was  improper. 
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3591  PERMIT:  bad  user  name  "%2* 

You  have  used  a  user  name  which  is  not  defined  on  the  system. 

3592  PERMIT:  Relation  '%1'  not  owned  by  you 

You  must  own  the  relation  before  issuing  protection  constraints. 

3593  PERMIT:  Relation  '%1'  must  be  a  real  relation  (not  a  view) 

You  can  not  define  permissions  on  views. 

3594  PERMIT  on  %1:  bad  day-of-week  '%2' 

The  day-of-week  code  was  unrecognized. 

3595  PERMIT  on  %1:  only  the  DBA  can  use  the  PERMIT  statement 

Since  only  the  DBA  can  have  shared  relations,  only  the  DBA  can  issue  permit  state¬ 
ments. 

3700  Tree  buffer  overflow  in  query  modification 

3701  Tree  build  stack  overflow  in  query  modification 

Bad  news.  An  internal  buffer  has  overflowed.  Some  expression  is  too  large.  Try  mak¬ 
ing  your  expressions  smaller. 
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NAME 

One  Variable  Query  Processor  error  message  summary 
SYNOPSIS 

Error  numbers  4000  —  4499. 

DESCRIPTION 

These  error  messages  can  be  generated  at  run  time.  The  One  Variable  Query  Processor  actually 
references  the  data,  processing  the  tree  produced  by  the  parser.  Thus,  these  error  messages  are 
associated  with  type  conflicts  detected  at  run  time. 

ERRORS 

4100  OVQP  query  list  overflowed 

This  error  is  produced  in  the  unlikely  event  that  the  internal  form  of  your  interaction 
requires  more  space  in  the  one  variable  query  processor  than  has  been  allocated  for  a 
query  buffer.  There  is  not  much  you  can  do  except  shorten  your  interaction  or  recom¬ 
pile  OVQP  with  a  larger  query  buffer. 

4101  numeric  operation  using  char  and  numeric  domains  not  allowed 

Occasionally,  you  will  be  notified  by  OVQP  of  such  a  type  mismatch  on  arithmetic 
operations.  This  only  happens  if  the  parser  has  not  recognized  the  problem. 

4102  unary  operators  are  not  allowed  on  character  values 

4103  binary  operators  cannot  accept  combinations  of  char  and  numeric  fields 

4104  cannot  use  aggregate  operator  "sum"  on  character  domains 
41  OS  cannot  use  aggregate  operator  "avg"  on  character  domains 

These  errors  indicate  type  mismatches  —  such  as  trying  to  add  a  number  to  a  character 
string. 

m 

4106  the  interpreters  stack  overflowed  --  query  too  long 

4107  the  buffer  for  ASCII  and  CONCAT  commands  overflowed 

More  buffer  overflows. 

4108  cannot  use  arithmetic  operators  on  two  character  fields 

4109  cannot  use  numeric  values  with  CONCAT  operator 

You  have  tried  to  perform  a  numeric  operation  on  character  fields. 

4110  floating  point  exception  occurred. 

If  you  have  floating  point  hardware  instead  of  the  floating  point  software  interpreter, 
you  will  get  this  error  upon  a  floating  point  exception  (underflow  or  overflow)  Since 
the  software  interpreter  ignores  such  exceptions,  this  error  is  only  possible  with  float¬ 
ing  point  hardware. 

41 1 1  character  value  cannot  be  converted  to  numeric  due  to  incorrect  syntax. 

When  using  inti,  int2.  int4,  float4,  or  float8  to  convert  a  character  to  value  to  a 
numeric  value,  the  character  value  must  have  the  proper  syntax.  This  error  will  occur 
if  the  character  value  contained  non-numeric  characters. 

4112  ovqp  query  vector  overflowed 
Similar  to  error  4100. 

4199  you  must  convert  your  6.0  secondary  index  before  running  this  query! 

The  internal  format  of  secondary  indices  was  changed  between  versions  6.0  and  6.1  of 
rNGRES.  Before  deciding  to  use  a  secondary  index  OVQP  checks  that  it  is  not  a  6.0  in¬ 
dex.  The  solution  is  to  destroy  the  secondary  index  and  recreate  it. 
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NAME 

Decomposition  error  message  summary 
SYNOPSIS 

Error  numbers  4500  -  4999. 

DESCRIPTION 

These  error  messages  are  associated  with  the  process  of  decomposing  a  multi-variable  query 
into  a  sequence  of  one  variable  queries  which  can  be  executed  by  OVQP. 

ERRORS 

4602  query  involves  too  many  relations  to  create  aggregate  function  intermediate  result. 

In  the  processing  of  aggregate  functions  it  is  usually  necessary  to  create  an  intermedi¬ 
ate  relation  for  each  aggregate  function.  However,  no  query  may  have  more  than  ten 
variables.  Since  aggregate  functions  implicitly  increase  the  number  of  variables  in  the 
query,  you  can  exceed  this  limit.  You  must  either  break  the  interaction  apart  and  pro¬ 
cess  the  aggregat  functions  separately  or  you  must  recompile  INGRES  to  support  more 
variables  per  query. 

4610  Query  too  long  for  available  buffer  space  (qbufsize). 

4611  Query  too  long  for  available  buffer  space  (varbufsiz) 

4612  Query  too  long  for  available  buffer  space  (sqsiz) 

4613  Query  too  long  for  available  buffer  space  (stacksiz) 

4614  Query  too  long  for  available  buffer  space  (agbufsiz). 

These  will  happen  if  the  internal  form  of  the  interaction  processed  by  decomp  is  too 
long  for  the  available  buffer  space.  You  must  either  shorten  your  interaction  or 
recompile  decomp.  The  name  in  parenthesis  gives  the  internal  name  of  which  buffer 
was  loo  smaiJ. 

4615  Aggregate  function  is  too  wide  or  has  too  many  domains. 

The  internal  form  of  an  aggregate  function  must  not  contain  more  than  49  domains  or 
be  more  than  498  bytes  wide.  Try  breaking  the  aggregate  function  into  two  or  more 
pans. 

4620  Target  list  for  "retrieve  unique"  has  more  than  49  domains  or  is  wider  than  498  bytes. 
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NAME 

Daia  Base  Utility  error  message  summary' 

SYNOPSIS 

Error  numbers  5000  —  5999 
DESCRIPTION 

The  Data  Base  Utility  functions  perform  almost  ail  tasks  which  are  not  directly  associated  with 
processing  queries.  The  error  messages  which  they  can  generate  result  from  some  syntax 
checking  and  a  considerable  amount  of  semantic  checking. 

ERRORS 

5001  PRINT:  bad  relation  name  %0 

You  are  trying  to  prim  a  relation  which  doesn't  exist. 

5002  PRINT:  %0  is  a  view  and  can't  be  printed 
The  only  way  to  print  a  view  is  by  retrieving  it. 

5003  PRINT:  Relation  %0  is  protected. 

You  are  not  authorized  to  access  this  relation. 

5102  CREATE:  duplicate  relation  name  %0 

You  are  trying  to  create  a  relation  which  already  exists. 

5103  CREATE:  %0  is  a  system  relation 

You  cannot  create  a  relation  with  the  same  name  as  a  system  relation.  The  system 
depends  on  the  fact  that  the  system  relations  are  unique. 

5104  CREATE  %0:  invalid  attribute  name  %1 

This  will  happen  if  you  try  to  create  a  relation  with  an  attribute  longer  than  12  charac¬ 
ters. 

5105  CREATE  %0:  duplicate  attribute  name  %1 

Attribute  names  in  a  relation  must  be  unique.  You  are  trying  to  create  one  with  a  du¬ 
plicated  name. 

5106  CREATE  %0:  invalid  attribute  format  "%2"  on  attribute  %1 

The  allowed  formats  for  a  domain  are  cl  —  c255,  il,  i2,  i4,  f4  and  f8.  Any  other  for¬ 
mat  will  generate  this  error. 

5107  CREATE  %0:  excessive  domain  count  on  attribute  %1 

A  relation  cannot  have  more  than  49  domains.  The  origin  of  this  magic  number  is  ob¬ 
scure.  This  is  very  difficult  to  change. 

5108  CREATE  %0:  excessive  relation  width  on  attribute  %1 

The  maximum  number  of  bytes  allowed  in  a  tuple  is  498.  This  results  from  the  deci¬ 
sion  that  a  tuple  must  fit  on  one  UNIX  "page".  Assorted  pointers  require  the  14  bytes 
which  separates  498  from  512.  This  "magic  number*  is  very  hard  to  change. 

5201  DESTROY:  %0  is  a  system  relation 

The  system  would  immediately  stop  working  if  you  were  allowed  to  do  this. 

5202  DESTROY:  %0  does  not  exist  or  is  not  owned  by  you 
To  destroy  a  relation,  it  must  exist,  and  you  must  own  it. 

5203  DESTROY:  %0  is  an  invalid  integrity  constraint  identifier 

Integers  given  do  not  identify  integrity  constraints  on  the  specified  relation.  For  exam¬ 
ple:  If  you  were  to  type  "destroy  permit  parts  1,  2,  3",  and  1,  2,  or  3  were  not  the 
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numbers  "help  permit  parts"  prints  out  for  permissions  on  parts,  you  would  get  this  er¬ 
ror, 

5204  DESTROY:  %0  is  an  invalid  protection  constraint  identifier 

Integers  given  do  not  identify  protection  constraints  on  the  specified  relation.  Example 
as  for  error  5203. 

5300  INDEX:  cannot  find  primary  relation 

The  relation  does  not  exist  —  check  your  spelling. 

5301  INDEX:  more  than  maximum  number  of  domains 

A  secondary  index  can  be  created  on  at  most  six  domains. 

5302  INDEX,  invalid  domain  %0 

You  have  tried  to  create  an  index  on  a  domain  which  does  not  exist. 

5303  INDEX:  relation  %0  not  owned  by  you 

You  must  own  relations  to  put  indicies  on  them. 

5304  INDEX:  relation  %0  is  already  an  index 
INGRES  does  not  permit  tertiary  indicies. 

5305  INDEX:  relation  %0  is  a  system  relation 

Secondary  indices  cannot  be  created  on  system  relations. 

5306  INDEX:  %0  is  a  view  and  an  index  can’t  be  built  on  it 

Since  views  are  not  physically  stored  in  the  database,  you  cannot  build  indicies  on 
them. 

5401  HELP:  relation  %0  does  not  exist 

5402  HELP:  cannot  find  manual  section  "%0" 

Either  the  desired  manual  section  does  not  exist,  or  your  system  does  not  have  any 
on-line  documentation. 

5403  HELP:  relation  %0  is  not  a  view 

Did  a  "help  view"  (which  prints  view  definition)  on  a  nonview.  For  example:  "help 
view  overpaidv"  prints  out  overpaidv's  view  definition. 

5404  HELP:  relation  %0  has  no  permissions  on  it  granted 

5405  HELP:  relation  %0  has  no  integrity  constraints  on  it 

You  have  tried  to  print  the  permissions  or  integrity  constraints  on  a  relation  which  has 
none  specified. 

5410  HELP:  tree  buffer  overflowed 

5411  HELP:  tree  stack  overflowed 

Still  more  buffer  overflows. 

5500  MODIFY:  relation  %0  does  not  exist 

5501  MODIFY:  you  do  not  own  relation  %0 

You  cannot  modify  the  storage  structure  of  a  relation  you  do  not  own. 

5  502  MODIFY  %0:  you  may  not  provide  keys  on  a  heap 
Bv  definition,  heaps  do  not  have  keys, 
v*  MODIFY  ^>0:  too  many  keys  provided 

v  zzn  only  have  49  keys  on  any  relation. 
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5504  MODIFY  %0:  cannot  modify  system  relation 

System  relations  can  only  be  modified  by  using  the  sysmod  command  to  the  shell;  for 
example 

sysmod  dbname 

5507  MODIFY  %0:  duplicate  key  "%1" 

You  may  only  specify  a  domain  as  a  key  once. 

5508  MODIFY'  %0:  key  width  (%1)  too  large  for  isam 

When  modifying  a  relation  to  isam,  the  sum  of  the  width  of  the  key  fields  cannot 
exceed  245  bytes. 

5510  MODIFY  %0:  bad  storage  structure 

The  valid  storage  structure  names  are  heap,  cheap,  isam,  cisam,  hash,  and  chash. 

5511  MODIFY  %0:  bad  attribute  name  "%1" 

You  have  specified  an  attribute  that  does  not  exist  in  the  relation. 

5512  MODIFY  %0:  "%r  not  allowed  or  specified  more  than  once 

You  have  specified  a  parameter  which  conflicts  with  another  parameter,  is  inconsistant 
with  the  storage  mode,  or  which  has  already  been  specified. 

5513  MODIFY  %0:  fillfactor  value  %1  out  of  bounds 
Fiil/aaor  must  be  between  1  and  100  percent. 

5514  MODIFY  %0:  minpages  value  %1  out  of  bounds 
M inpages  must  be  greater  than  zero. 

5515  MODIFY  %0:  "%1"  should  be  "fillfactor",  "maxpages",  or  "minpages" 

You  have  specified  an  unknown  parameter  to  modify . 

5516  MODIFY  %0:  maxpages  value  %1  out  of  bounds 

5517  MODIFY  %0:  minpages  value  exceeds  maxpages  value 

5518  MODIFY  %0:  invalid  sequence  specifier  "%r  for  domain  %2. 

Sequence  specifier  may  be  "ascending"  (or  "a")  or  "descending"  (or  "d")  in  a  modi¬ 
fy.  For  example: 

modify  pans  to  heapsort  on 

pnumiascending, 

pname:descending 

5519  MODIFY:  %0  is  a  view  and  can’t  be  modified 
Only  physical  relations  can  be  modified. 

5520  MODIFY:  %0:  sequence  specifier  "%1"  on  domain  %2  is  not  allowed  with  the  specified 
storage  structure. 

Sortorder  may  be  supplied  only  when  modifying  to  heapsort  or  cheapsort. 

5600  SAVE,  cannot  save  system  relation 

System  relations  have  no  save  date  and  are  guaranteed  to  stay  for  the  lifetime  of  the 
data  base. 

5601  SAVE:  bad  month  "%<T 

5602  SAVE:  bad  day  "%0" 

5603  SAVE:  bad  year  "%0" 
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This  was  a  bad  month,  bad  day,  or  maybe  even  a  bad  year  for  INGRES. 

5604  SAVE:  relation  % 0  does  not  exist  or  is  not  owned  by  you 

5800  COPY:  relation  %0  doesn't  exist 

5801  COPY:  attribute  %0  in  relation  %1  doesn't  exist  or  it  has  been  listed  twice 

5803  COPY:  too  many  attributes 

Each  dummy  domain  and  real  domain  listed  in  the  copy  statement  count  as  one  attri¬ 
bute.  The  limit  is  150  attributes. 

5804  COPY:  bad  length  for  attribute  %0.  Length— "%r 

5805  COPY:  can’t  open  file  %0 

On  a  copy  "from",  the  file  is  not  readable  by  the  user. 

5806  COPY:  can’t  create  file  %0 

On  a  copy  "into",  the  file  is  not  creatable  by  the  user.  This  is  usually  caused  by  the 
user  not  having  write  permission  in  the  specified  directory. 

5807  COPY:  unrecognizable  dummy  domain  "%0" 

On  a  copy  "into",  a  dummy  domain  name  is  used  to  insert  certain  characters  into  the 
Unix  file.  The  domain  name  given  is  not  valid. 

5808  COPY:  domain  %0  size  too  small  for  conversion. 

There  were  %2  tuples  successfully  copied  from  %3  into  %4 

When  doing  any  copy  except  character  to  character,  copy  checks  that  the  field  is  large 
enough  to  hold  the  value  being  copied. 

5809  COPY:  bad  input  string  for  domain  %0.  Input  was  "%2*.  There  were  %2  tuples  suc¬ 
cessfully  copied  from  %3  into  %4 

This  occurs  when  converting  character  strings  to  integers  or  floating  point  numbers. 
The  character  string  contains  something  other  than  numeric  characters  *0- 
9,+,-,blank,etc.). 

5310  COPY:  unexpected  end  of  file  while  filling  domain  %0. 

There  were  %1  tuples  successfully  copied  from  %2  into  %3 

5811  COPY:  bad  type  for  attribute  %0.  Type— ”%1" 

The  only  accepted  types  are  i,  f,  c,  and  d. 

5812  COPY:  The  relation  "0/o0"  has  a  secondary  index.  The  index (es)  must  be  destroyed  be¬ 
fore  doing  a  copy  "from" 

Copy  cannot  update  secondary  indices.  Therefore,  a  copy  "from"  cannot  be  done  on 
an  indexed  relation. 

5813  COPY:  You  are  not  allowed  to  update  the  relation  %0 
You  cannot  copy  into  a  system  relation  or  secondary  index. 

5814  COPY:  You  do  not  own  the  relation  %0. 

You  cannot  use  copy  to  update  a  relation  which  you  do  not  own.  A  copy  "into"  is  al¬ 
lowed  but  a  copy  "from"  is  not. 

5815  COPY:  An  umerminated  "cO"  field  occurred  while  filling  domain  %0.  There  were  %1 
tuples  successfully  copied  from  %2  into  %3 

A  string  read  on  a  copy  "from"  using  the  "cO"  option  cannot  be  longer  than  1024  char¬ 
acters. 

58 1  o  COPY:  The  full  pathname  must  be  specified  for  the  file  %0 
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The  file  name  for  copy  must  start  with  a  7". 

5817  COPY:  The  maximum  width  of  the  output  file  cannot  exceed  1024  bytes  per  tuple 

The  amount  of  data  to  be  output  to  the  file  for  each  tuple  exceeds  1024.  This  usually 
happens  only  if  a  format  was  mistyped  or  a  lot  of  large  dummy  domains  were  specified. 

5818  COPY:  %0  is  a  view  and  can’t  be  copied 
Only  physical  relations  can  be  copied. 

5819  COPY:  Warning:  %0  duplicate  tuples  were  ignored. 

On  a  copy  "from",  duplicate  tuples  were  present  in  the  relation. 

5820  COPY:  Warning:  %0  domains  had  control  characters  which  were  converted  to  blanks. 

5821  COPY:  Warning:  %0  cO  character  domains  were  truncated. 

Character  domains  in  cO  format  are  of  the  same  length  as  the  domain  length.  You  had 
a  domain  value  greater  than  this  length,  and  it  was  truncated. 

5822  COPY:  Relation  %0  is  protected. 

Y ou  are  not  authorized  to  access  this  relation. 
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NAME 

GEO-QUEL  error  message  summary 
SYNOPSIS 

Error  numbers  30000  —  30999. 

DESCRIPTION 

The  following  errors  can  be  generated  by  the  geo-quel  subsystem  of  INGRES.  These  errors  are 
ail  associated  with  errors  in  the  graphics  processor. 

ERRORS 

30210  GEO-QUEL  is  creating  a  MAPRELATION  relation 

30300  line  %0,  In  attempting  to  do  a  MAP,  SHADE,  or  OVERLAY  the  relation  '%1'  does 
not  exist  or  is  not  owned  by  you 

30301  line  %0,  Failed  to  obtain  information  to  put  a  tuple  in  MAPRELATION  relation 
30310  line  %0.  Failed  to  complete  MAP 

30330  line  %0,  Failed  while  building  temporary  relation  in  SHADE  command 

30331  line  %0,  Maximum  polygon  value  is  0.0  which  causes  floating  point  exception 

30332  line  %0,  Too  many  sides  (maxside)  in  polygon  (zoneid:  %1,  groupid:  %2) 

30340  line  %0,  Failed  while  trying  to  obtain  range  limits  for  axes  in  POINTGRAPH  or  LINE- 
GRAPH 

30341  line  %0,  The  linetype  specified  (%1)  in  the  linegraph  command  does  not  make  sense 
for  the  device 

30342  line  %0,  %I  does  not  exist  or  cannot  be  accessed  by  you 

30350  line  %0,  There  is  no  current  center  definition  for  this  map:  %1 

30400  line  %0,  Error  in  creating  destination  file  '%!'  in  SAVEMAP 

30401  line  %0,  Too  many  domains  for  SHADE(shadedoms) 

30402  line  %0,  Too  many  domains  for  POINTGRAPH  of  LINEGRAPH  (graphdoms) 

30410  line  %0,  Error  in  creating  destination  file  '%1'  in  SAVEMAP 

30420  line  You  may  specify  only  one  boundary  when  using  'cellcoum'  and  'cellwidth' 

30421  line  %0,  Only  one  cellwidth  per  command  has  meaning 

30422  line  %Q,  Only  one  cellcoum  per  command  has  meaning 

30423  line  0/o0.  Only  one  upper  bound  per  command  has  meaning 

30424  line  %0,  Only  one  lower  bound  per  command  has  meaning 

30425  line  %0,  %1  does  not  exist  or  cannot  be  accessed  by  you 


